This section shows different options of exchanging data and control information with IBM Lotus Expeditor integrator from business use case perspective. IT architects and developers who create business use cases will find important information in here for designing their solutions around Expeditor integrator.
It is explained which data can be exchanged with the Expeditor integrator. Especially, message types, their structure, header properties and values are documented.

Message Flows

Overview

The Expeditor integrator is an event- and message-driven application. The standard OSGi Event Admin service is used to control local application flows. This allows for independent, stable and fast task processing.
Messages which are received by the Expeditor integrator trigger defined application events (e.g. ACS flow trigger events). This gives external (back-end) processes the opportunity to remotely control the behavior of the Expeditor integrator and to also remotely run certain actions in transactional context.

Figure 3 shows how messages and events are handled by the Expeditor integrator components.

Figure 3: Messaging architecture overview: message and data flow in the Expeditor integrator

Please, refer to the following chapters for detailed message and event flows that correspond to defined received messages and business use cases. The example business use cases of chapter 1.2.2 Example Business Use Cases for Retail will be taken to explain the generally available functionality of Expeditor integrator’s message interaction.

Message carries data from the Back-end to the Remote Location

The example Business Use Cases BUC_1 and BUC_3 from chapter 1.2.2 Example Business Use Cases for Retail are very similar from the perspective of the message and event flow. Figure 4 shows how a message carrying a file is processed by the Expeditor integrator. The difference between the two use cases is only in step 6 during which the transported file needs to be copied to the target directory, either a FTP directory (BUC_1) or the local file system (BUC_3). Other supported resources are SSH servers, databases or even other local queues and topics. For databases, the incoming message could either transport SQL statements or XML data describing the data record.

If the default Expeditor integrator ReqInQ is used, the Dispatcher Services will preprocess all received messages and fire Expeditor integrator application events. These events are captured by the Application Control Service (ACS) which further kicks off the corresponding configured ACS flow and its activities.
Alternatively, a JMS_DESTINATION_ADAPTER could directly monitor a configured local InQ and issue the ACS Flow trigger event.

Please, refer to section 4 Add New Logic - ACS Service for details about the Application Control Service.


Figure 4: Expeditor integrator message and event flow for BUC_1 and BUC_3

Figure 4 is an example for price updates which need to be applied to the PoS systems. Messages containing price update commands are sent to the Expeditor integrator. The received messages are converted into price update files which are transferred to the local file system (6a), the 4690 Controller via FTP/SSH (6b), committed as records to a connected database (6c) or even put in another local queue/topic as messages with or without a prior conversion.

The following steps are included:

1. Price updates were created
2. BSB back-end triggers the creation of messages that contain price update commands for the PoS systems and sends them to the remote location (retail store).
3. Queue Dispatcher recognizes message carrying price update data, moves it to a local queue and fires a ACS flow trigger event.
4. This event triggers the price update flow in the Application Control Service (ACS).
5. The ACS price update flow retrieves the original message and extracts the price update command(s) and writes them into a price update file or record.
6. The created file or record is written to the defined destination (either to the local file system, see 6a, the FTP / SSH Server e.g 4690, see 6b, or connected database, see 6c).
7. Log and business events are created and forwarded (either to the monitoring back-end, e.g. business events – see 7a, or the TEC – see 7b)

Message carries data from the Remote Location to the Back-end

Business Use Case BUC_2 from chapter 1.2.2 Example Business Use Cases for Retail defines how files which appear in given directories (e.g. FTP directories), records in a given database or even messages in other local queues/topics must be captured and transferred back to the BSB back-end.
Resource Adapters can be configured which perform the required directory, database and queue monitoring. As soon as the expected file, database record(s) or message(s) appear, the Resource Adapter reports this to the Resource Monitor that fires a defined Expeditor integrator application event. The Application Control Service (ACS) captures this event and kicks off the corresponding flow and its activities. During these activities, the file, database records(s) or message(s) are captured, packaged into a new JMS message and sent to the BSB back-end. Database result sets are transformed into the Expeditor integrator XML structure for database records (see chapter 2.5.2 Expeditor integrator XML Data Structure for DB Operations for details about this XML structure).

Figure 5 shows the event flow using the following example:
Daily PoS transaction data must be captured from the PoS systems. The transaction data is retrieved as files either from the local file system or from the 4690 via FTP / SSH, or as record(s) from a connected database. The Expeditor integrator creates messages out of the data and sends them to the BSB back-end.

The Resource Adapters and the fired events can be configured so that different flows can be created for addressing different use cases instantly.

Please, refer to section 4 Add New Logic - ACS Service for details about the Application Control Service.


Figure 5: Expeditor integrator message and event flow for BUC101

The following steps are required for the example in Figure 5:

1. Transaction data file is created (on the local file system – see 1a, or on the 4690 – see 1b, a transaction record is created in the database, see 1c), or a new message was received. The Resource Adapters realize the existence of the transaction data and report this to the Resource Monitor.
2. The Resource Monitor publishes an Expeditor integrator trigger event that indicates that a resource (transaction data) appeared.
3. The event triggers the corresponding flow in the Application Control Service (ACS).
4. ACS Activities capture the new transaction data (either from the local file system – see 4a, the 4690 Controller – see 4b, or the connected database, see 4c).
5. ACS Activities create a BSB messaging back-end compliant message carrying the transaction data from the resource data and put them in the Lotus Expeditor micro broker out queue.
6. The Dispatcher Service routes the message(s) to the correct queue locally which is bridged with a distinct queue of the BSB messaging back-end.
7. Log and business events are created and forwarded (either to the monitoring back-end, e.g. business events – see 7a, or the TEC – see 7b)
8. The BSB back-end messaging system flows process the received transaction data and store them appropriately.

Message Types

The concept of different message types was introduced in order to be able to identify and dispatch known incoming messages and finally trigger corresponding actions. This mapping of different message types to use case dependent actions (ACS Flows) for processing of the message is done through defined JMS Custom Message Header properties. The properties

• MessagePurpose, that currently differentiates between data and control messages
• TransportType (whether FTP, local file system or DB targets are addressed) and
• ResourceType that identifies which resource is finally selected (pre-defined or custom value).

identify the type of message. The ResourceType can be used to further group messages which trigger common behavior on the Expeditor integrator runtime (e.g. common ACS Flows).

If the Dispatcher Service is used on the Expeditor integrator default ReqInQ, incoming messages are moved to local queues depending on the values provided in the JMS Custom Header properties MessagePurpose, TransportType and ResourceType. Since the Queue Dispatcher is configurable, the local target queue can also be configured.

Both, the Dispatcher Service and the JMS_DESTINATION_ADAPTER trigger OSGi Event Admin Service events when a matching message was received. These events will further trigger the corresponding ACS Flow (ACS Flow trigger events). They are also assembled from the JMS Custom Header properties:
Regarding to Figure 6, the flow trigger event would be:
The Flow Trigger Events basically wire resource changes, for example incoming messages or appearing files in given source directories, together with corresponding ACS Flows which make up a defined use case to further process the triggering resource data (see Figure 6).


Figure 6: JMS Message Header property to ACS Flow relationship: Depending on the message header properties, he Dispatcher Service moves incoming messages to different local queues for parallel processing by different ACS Flows.

Table 1: Message Types

Message type	Direction	Consumer (used by application x)	Description
FileTransfer data message	BSB -> XPDinteg	ACS Flow	Message carries a file for further processing and transmission (either to local file system or to file server, e.g. FTP/SSH)
FileRequest data message	BSB <-> XPDinteg	ACS Flow	Message which requests to retrieve a file from local file system, FTP/SSH server. Created reply message is of type FileTransfer message.
DBRecordUpdate data message	BSB -> XPDinteg	ACS Flow	Message carries data and/or database commands for updating and inserting records into a target database.
DBRecordSelect data message	BSB <-> XPDinteg	ACS Flow	Message carries commands to retrieve a database result set. Created reply message is of type DBRecordSelect message.
MessageForward data message	BSB -> XPDinteg	Dispatcher, ACS Flow, JMS_Adapter	Message is received at one local queue/provider and will be moved to another (local) queue/messaging provider.
Control messages: ConfigUpdate ConfigRetrieval DrainQueue BrowseQueue BrowseDirectory ExecuteScript Maintenance HouseKeeping ISACollector PlatformRestart	BSB -> XPDinteg	ACS Flows	Control messages are received at a separate queue (CtrlQ) and trigger Expeditor integrator runtime management actions. These actions are executed within ACS Flows, e.g. configuration update request drain request for a local queue browse request for a local queue browse request for a given directory script execution request trigger Maintenance Mode, HouseKeeping, ISA collector and platform restart request
Event messages	XPDinteg -> BSB	BSB Flow	Messages which contain log and/or business events (e.g. CBE events).

Table 3 and Table 4 in chapter 2.4 Currently Supported Messages list the currently supported message types that can be received. The corresponding application events are listed in Table 27 (see section 4 Add New Logic - ACS Service).

These events are required to trigger defined actions when a given message is received. Please, refer to section 4 Add New Logic - ACS Service for details of how Expeditor integrator application events trigger use case dependent flows.

JMS Custom Header Properties

Table 2 shows the JMS message header definition that is used for messages exchanged between Expeditor integrator and the back-end (BSB) or other messaging systems. All JMS Custom Header properties are provided as value pairs in String format.

Some properties are always mandatory so that the message can be processed. In the case that the property ResourceType is not provided or is of an unknown type, all other custom header properties which are required to fulfill a given use case must also be provided.
Note: Property names are in Mixed Case (starting with capital letter). All property values are in Capital letters if they are single words or in Mixed Case if they consist of multiple words.
E.g.: If the MessagePurpose=”FileTransfer” and the ResourceType is not set, the TransportType, the DestinationPath, DestinationName, TransferMode, DestinationCreationMode properties become mandatory as well.

Table 2: JMS message custom header definition

Custom Header Property	Type	Currently Supported Values
LocationId (mandatory)	String	LocationId is the NodeID: unique identification for the Expeditor integrator instance (e.g. StoreId)
MessagePurpose (mandatory)	String	Data transfer request message. Supported values: FileTransfer | FileRequest | DBRecordUpdate | DBRecordSelect | MessageForward | ConfigUpdate | ConfigRetrieval | DrainQueue | BrowseQueue | ExecuteScript | BrowseDirectory | Maintenance | HouseKeeping | ISACollector | PlatformRestart | HttpGet (RequestMessage for HTTP resources) | HttpPost | HttpPut | HttpDelete
ResourceType (always recommended)	String	Name of the type of resource that is accessed. There are default values available for using the Dispatcher Service and/or default ACS Flows (e.g. name of the file type according to the ResourceType / FileType definition, e.g. “PriceUpdFile”) Possible values (constants) are provided after the table Custom values are possible.
Description	String	description of the message payload
TransportType (mandatory if ResourceType is not set or not known)	String	Type of resource system that is accessed: FTP | LocalFileSystem | SSH | MESSAGE | DB | HTTP | HTTPS
TransferMode	String	Data transmission mode: ASCII | BINARY
DestinationCreationMode	String	target resource creation mode if same resource already exists: for files: APPEND | OVERWRITE for DB records: INSERT | UPDATE | TABLE_CREATE | UPDATE_INSERT for HTTP: not applicable. The HTTP commands POST and PUT define the destination creation mode: POST causes appending of data if the target resource already exists. PUT creates resource on HTTP server – if resource already exists, it will be overwritten.
TransferConfirmationMode	String	What needs to be done with the source data (e.g. a source file) after successful transfer: for files: NONE | DELETE | RecreateZero | WriteOtherFile for DB records: INSERT | UPDATE | SQL for HTTP GET: NONE | DELETE | RecreateZero | WriteOtherFile
WriteOtherFileName	String	name of the resource that is re-created (for TransferConfirmationMode=WriteOtherFile); format equals DestinationName
DestinationPath	String	path to the resource that needs to be updated or retrieved (e.g. directory path, database URI) is used in conjunction with the DestinationName property (forward slashes only) mandatory for HTTP: This must property must always be provided (even as empty string) and must contain the absolute path from the configured htdocs directory (Note: leading ‘/’ is required!)
DestinationName	String	name of the resource to be updated (e.g. target file name) name of the resource to be retrieved (e.g. source file name + directory + jndiDestinationKey of queue) name of the target Datasource is used in conjunction with the DestinationPath property (forward slashes only)
ResourceCmd	String	contains any command that needs to be executed (e.g. SQL statements in case of the database access); Please, find more information after this table.
Credentials	String	encrypted or not encrypted Use the provided PasswordUtil (installed with the Expeditor integrator tools) for encrypting passwords!). e.g. user name and password for securing Activities (see chapter 5.12.1 Securing Operations in Ref_1) for DB access: User:<db_username>;Password:<db_password> Note: This is not used for the Resource Adapters (see ResourceCmd)
ResourceAuthenticationType (optional)	String	Type of authentication mechanism that is used by the Resource Adapter for accessing a resource: for HTTP: NONE (no authentication, BasicAuth (for Basic Authentication, default, DigestAccessAuth (for Digest Access Authentication)
TransferPriority	INT	Is the priority that can be used to transfer the requested resources in a certain order (e.g. requested files need to be transferred with this priority)
MessageId (mandatory)	String	unique message ID that corresponds to AI’s EventId (22-digits) for received messages. Messages created by the Expeditor intgrator get a unique ID following a defined schema (see chapter 2.4 3 JMS Custom Header Creation for Messages from Expeditor integrator to Back-end (outbound) )
TransactionId (mandatory)	String	is the ID of a transaction. If a transaction consists of more then one message (e.g. carrying a split file), the TransactionId would be the same for all these messages. The TransactionId is also used to identify a reply message that was triggered by a request message (same ID).
Encoding	String	Type of data encoding
MessagePriority	INT	Is mapped to the standard JMS message priority and is used by the JMS handlers. Messages with the highest priority are processed first. (possible values: 0-9; [0]-lowest, [9]-highest)
MessageSrcId (mandatory)	String	HOST Name generating the message: AI Messaging Server or the host name of the Expeditor integrator server
ResourceSize	String	Size of the resource data in the payload in KBytes (e.g. file size of a transferred file)
TimeStamp (recommended)	String	Source file creation time in the source directory for file transfer Expeditor integrator -> back-end -required for Housekeeping
TTL (recommended)	LONG	Time to live value of the message after reception at the receiving system. TTL is required for Housekeeping (expects the TTL in ms since 1970) to determine whether a message is expired. If the message is sent to Expeditor integrator using the Dispatcher Service or any configured JMS Destination Adapter: The TTL must be provided as RELATIVE value by the message creator (provided value is treated relative to the local reception time of the receiving system) On reception, the TTL value is converted into and replaced with an absolute time by the receiving system. The new absolute time is computed in ms since 1970 from the local time at reception plus the provided relative TTL in the message header (in order to avoid time sync issue). If the TTL is given as Activity Context Parameter to the MessageWrite or FileToMessageWrite activities as relative value the TTL will be converted into an absolute time and the TTL message header will also be replaced with this absolute time value in ms since 1970. If the message is sent directly to a queue in the Expeditor where it is not handled by the Dispatcher Service or a JMS Destination Adapter the message creator must provide the TTL time as ABSOLUTE value in ms since 1970. Otherwise, it will be used incorrectly by the Housekeeping Activity. In addition, a custom JMS message header named Expiry must be provided and set to the String value "ON".
SequenceNo (mandatory)	INT	continuous numbering of concatenated messages, for example, carrying chunks of one file (also )
EndOfData (mandatory)	Boolean	TRUE | FALSE indicates last message out of a series of concatenated messages (e.g. carrying a large file)
BuildInterval (mandatory)	LONG	Time in milliseconds during which concatenated messages are written in the same target (e.g. a file)
HeaderVersion (mandatory)	String	Indicates the Expeditor integrator JMS Custom Message Header version.

The following property values (constants) are currently supported:

MessagePurpose values for:

• file handling: FileTransfer | FileRequest
• application control: BrowseDirectory | ConfigUpdate | ConfigRetrieval | DrainQueue | BrowseQueue| ExecuteScript | Maintenance | HouseKeeping | ISACollector | PlatformRestart
• database access: DBRecordUpdate | DBRecordSelect
• message forwarding: MessageForward
• HTTP server access: HttpGet | HttpPost | HttpPut | HttpDelete

TransportType values for:

• FTP: FTP
• SSH: SSH
• local file system access: LocalFileSystem
• database access: DB
• message forwarding: MESSAGE
• HTTP server access: HTTP | HTTPS

There are pre-defined values for the ResourceType in order to group messages together for defined use cases (e.g. price updates). It also allows the use of the Expeditor integrator Dispatcher Service in order to achieve higher performance (higher throughput through parallel computing/execution of ACS Flows).

The following pre-defined ResourceTypes were initially created for the retail industry:

ResourceType values for:

• FTP Download: default=FtpFile
  Retail industry specific: PriceUpdFile | MappingDataFile | DiscountDataFile
• FTP Upload: default=FtpFile (This default value is only set if the TransportType=FTP and the ResourceType is not provided.)
  Retail industry specific: PosTransDataFile1 | PosTransDataFile2 | OtherTransDataFile | PosProdDataFile | TlogFile | CreditNotesFile | PaybackDataFile | EventsFile
• LocalFileSystem: default=LocalFileSystemFile (This default value is only set if the TransportType=LocalFileSystem and the ResourceType is not provided.)
  Retail industry specific: ScaleDataFile | PrintLabelFile | ShelfLabelFile | ConfigurationUpdateFile | ScriptFile
• SSH: SshFile (Default)
• database access: DBResource | default=DBResource
  messaging: MESSAGE (This is also the default value)
• HTTP server access: HttpResource (default)
• application specific content: CUSTOM

The DestinationName, DestinationPath, RecourceCmd and Credentials JMS Custom Header properties hold further resource access dependent information, e.g.
ResourceCmd values for:

• For MessagePurpose=FileTransfer | FileRequest and TransportType=FTP: ResourceCmd=FtpServer:value1;FtpServerPort:value2;FtpPassive:value3;FtpUser:value4;FtpPassword:value5;FtpType:value6)
  
  
• For MessagePurpose=FileTransfer | FileRequest and TransportType=SSH: ResourceCmd=SshServer:value1;SshServerPort:value2;SshUser:value4;SshPassword:value5;SshType:value6)
  
  
• For MessagePurpose=PlatformRestart:
  
  ResourceCmd=Command:{restart|stop};Param:console,reset
  
  Command defines whether to only stop or restart the complete Expeditor integrator runtime (WARNING: Only use stop if you really sure since a connection to the remote platform will not be available anymore!)
  Param allows restarting in console mode and with resetting the Expeditor integrator platform before starting it (deleting queues, logs etc.).
  
  
• For MessagePurpose=ConfigUpdate:
  
  ResourceCmd=FILE | ParamList;[Command:{restart|stop};Param:console,reset]
1. ResourceCmd=FILE: Message payload contains the new XPDinteg.xml file
   
   The new XPDinteg.xml file is detached to the <XPDINTEG_HOME>/config folder and overwrites the currently active configuration file. The Application Control Service (ACS) Update Flow (Default_ConfigUpdate.flow) is started to validate the new configuration XML structure and also create the new system configuration file (under /config/system).
   
   
2. ResourceCmd=ParamList: Message payload carries a list of configuration propertys which need to be updated (b):
   
   ResourceCmd =ParamList;[Command:{restart|stop};Param:console,reset]
   Message Payload contains the partial properties of XPDintegConfig.xml file (see XPDINTEG_CONFIG_XML structure in Error! Reference source not found.).
   
   Listing 1: The XPDINTEG_CONFIG_XML structure is used for updating single Expeditor integrator properties through the ConfigUpdate message.
   

   <?xml version="1.0" encoding="utf-8"?>
   

   <configurations>
   

        <configuration pid="com.ibm.rcp.integrator.customeventservice">
   

            <properties>
   

   <property name="MaintenanceMode" value="ON"/>
   

             </properties>
   

        </configuration>
   

   </configurations>
   

   …
   

   
   
   
3. ResourceCmd=UserConfigFILE: Message payload contains the new XPDintegRoles.xml file
   
   The new XPDintegRoles.xml file is detached to the <XPDINTEG_HOME>/config folder and overwrites the currently active User Admin store configuration file. The Application Control Service (ACS) Update Flow (Default_UserConfigUpdate.flow) is started to validate the new configuration XML structure.
   
   Recommendation: The XPDintegRoles.xml should be deleted at the end of the update flow since it contains sensitive information (by setting the property UpdatesFileAction=Delete in the common section of the XPDinteg.xml file).
   
   
4. ResourceCmd=UserConfigParamList: Message payload carries a list of configuration propertys which need to be updated in the User Admin store and/or XPDintegRoles.xml (c):
   
   ResourceCmd =UserConfigParamList;[Command:{restart|stop};Param:console,reset]
   
   Message Payload contains the partial properties of XPDintegRoles.xml file (see XPDINTEG_USERROLES_XML structure in Listing 2).
   
   Listing 2: The XPDINTEG_USERROLES_XML structure is used for updating single Expeditor integrator User Admin store configuration properties through the ConfigUpdate message.
   

   <?xml version="1.0" encoding="UTF-8"?>
   

   <configuration>
   

       <role name="uiadmin" description="Admin role for the XPDinteg GUI">
   

           <users>
   

   	<user username="xpdintegadmin" password="xpdintegadmin"/>
   

           </users>	
   

       </role>
   

       <role name="uiconfig" description="Config role for the XPDinteg GUI">
   

           <users>
   

   	<user username="xpdintegadmin" password="xpdintegadmin"/>
   

   	<user username="xpdintegconfig" password="xpdintegconfig"/>
   

           </users>
   

       </role>
   

       <role name="uimonitor" description="Monitor role for the XPDinteg GUI">
   

           <users>
   

   	<user username="xpdintegadmin" password="xpdintegadmin"/>
   

   	<user username="xpdintegconfig" password="xpdintegconfig"/>
   

   	<user username="xpdintegmonitor" password="xpdintegmonitor"/>
   

   	<user username="xpdintegtest" password="xpdintegtest"/>
   

           </users>
   

       </role>
   

       <role name="uitest" description="Test role for the XPDinteg GUI">
   

           <users>
   

   	<user username="xpdintegadmin" password="xpdintegadmin"/>
   

   	<user username="xpdintegtest" password="xpdintegtest"/>
   

           </users>
   

       </role>
   

       <role name="restadmin" description="Admin role for the REST Adapter">
   

           <users>
   

   	<user username="xpdintegadmin" password="xpdintegadmin"/>
   

   	<user username="xpdintegrestadmin" password="xpdintegrestadmin"/>
   

           </users>
   

       </role>
   

       <role name="restscriptexecute" description="Execute script role for the REST Adapter">
   

           <users>
   

   	<user username="xpdintegadmin" password="xpdintegadmin"/>
   

   	<user username="xpdintegrestadmin" password="xpdintegrestadmin"/>
   

   	<user username="xpdintegrestscriptexecute" password="xpdintegrestscriptexecute"/>
   

           </users>
   

       </role>
   

       <role name="restsupport" description="Support role for the REST Adapter">
   

           <users>
   

   	<user username="xpdintegadmin" password="xpdintegadmin"/>
   

   	<user username="xpdintegrestadmin" password="xpdintegrestadmin"/>
   

   	<user username="xpdintegrestsupport" password="xpdintegrestsupport"/>
   

           </users>
   

       </role>
   

       <role name="restresourcebrowser" description="Resource browser role for the REST Adapter">
   

           <users>
   

   	<user username="xpdintegadmin" password="xpdintegadmin"/>
   

   	<user username="xpdintegrestadmin" password="xpdintegrestadmin"/>
   

   	<user username="xpdintegrestresourcebrowser" password="xpdintegrestresourcebrowser"/>
   

           </users>
   

       </role>
   

       <role name="restuser" description="User role for the REST AdapterI">
   

           <users>
   

   	<user username="xpdintegadmin" password="xpdintegadmin"/>
   

   	<user username="xpdintegrestadmin" password="xpdintegrestadmin"/>
   

   	<user username="xpdintegrestuser" password="xpdintegrestuser"/>
   

           </users>
   

       </role>
   

   </configuration>
   

   
   
• For MessagePurpose=DBRecordUpdate or DBRecordSelect
  
  ResourceCmd=SQL | XPDINTEG_DBXML | XML
  
  
• For MessagePurpose=Maintenance
  
  ResourceCmd={ON | OFF}[;Command={restart|stop};Param:{console,reset} ]
  
  
• For MessagePurpose= anything (when a ExecuteLocalScript ACS Activity is included in any of the triggered flows)
  
  ResourceCmd=LocalScriptFile:<Path_to_local_script_file>
  (for example: ResourceCmd=LocalScriptFile:C:/temp/test.bat)
  
  
• For MessagePurpose=HttpGet | HttpPost | HttpPut | HttpDelete and TransportType=HTTP | HTTPS:
  
  ResourceCmd=HttpServer:value1;HttpServerPort:value2;HttpUser:value4;HttpPassword:value5;HttpMimeType:value6;HttpUserAgent:value7;HttpVersion:value8;HttpRetries:value9;HttpServerProxy:value10;HttpServerProxyPort:value11;HttpServerProxyUser:value12;HttpServerProxyPassword:value13;HttpAcceptSelfSignedCertificates:value14;HttpType:value15)
  
  Note: Please, use the property-value pairs of the XPDinteg.xml HTTP properties (e.g. ResourceCmd=HttpServer:192.168.1.2;HttpServerPort:21;HttpUser:test;HttpPassword:test;HttpMimeType:text/plain;HttpUserAgent:Mozilla/4.0;HttpVersion:1.1;HttpRetries:3;HttpServerProxy:127.0.0.1;HttpServerProxyPort:8080;HttpServerProxyUser:test;HttpServerProxyPassword:test;HttpType:DEFAULT)

Currently Supported Messages

JMS Custom Header Creation for Message Transfer between Back-end and Expeditor integrator

According to Table 2, the Expeditor integrator is able to process different types of messages (e.g. FileTransfer or FileRequest messages). These different message types are used to trigger different ACS Flows which implement default and customer use cases. Furthermore, the Dispatcher Service also uses the message types for message routing information (Note: The Dispatcher Service dispatches incoming messages on the Expeditor integrator default ReqInQ to different local queues for further – parallel – processing.).

The ResourceType property has priority over the TransportType property. If the

the ResourceType is set to its default value depending on the TransportType:

• TransportType=FTP and ResourceType is not set -> ResourceType=FtpFile
• TransportType=SSH and ResourceType is not set -> ResourceType=SshFile
• TransportType=LocalFileSystem and ResourceType is not set -> ResourceType=LocalFileSystemFile
• TransportType=DB and ResourceType is not set -> ResourceType=DBResource
• TransportType=MESSAGE and ResourceType is not set -> ResourceType=Message

Messages carry File Resource Data

Figure 7 shows the flow of messages that carry files, file content or fragments of files from the back-end to the (remote) install location of Expeditor integrator. The destination file is assembled and created in the given target directory by a defined set of ACS Activities. The triggered ACS Flow, Activities and the accessed target resource depend on the data type which is transferred (LocalFileSystem file, FTP file or SSH file).

The Activity set builds the ACS flow which was configured for processing of defined message types (default or custom flows and activities).


Figure 7: Process flow for inbound messages with file resource data

The JMS Destination Adapter monitors given local queues and topics of the used JMS provider (e.g. Lotus Expeditor micro broker). As soon as a matching resource appears (e.g. a message with MessagePurpose=FTP), the configured ACS Flow is triggered through the Flow Trigger Event. Different combination of the JMS Custom Header properties MessagePurpose, TransportType and ResourceType allow for starting different ACS Flows (see supported JMS Custom Header properties in chapter 2.3 JMS Custom Header Properties and 4.4 Resource Adapter configuration in Ref_1).

Figure 8 shows how the Dispatcher Service can be used. It moves messages to other local in queues and also fires ACS Flow Trigger Events. This can be configured and further refined in the inbound Resource Mapper configuration.

Note: The Dispatcher Service is not working in transactional context (“air gap”), but offers distributing of messages to different inbound queues for further parallel processing (faster and recommended for very large message bulks).



Figure 8: Process flow for inbound messages with file resource data using the Dispatcher Service (BUC_1 and BUC_2)

FileRequest messages can be sent to Expeditor integrator to query for specific file located on FTP/SSH file servers or on the local file system. The Request Message contains the resource location in the JMS Custom Header property DestinationPath and DestinationName. TransportType and ResourceType should be provided for further configuration details (ResourceType can also be used to map to a given Resource Mapper configuration in the XPDinteg.xml file).



Figure 9: Process flow for outbound messages: FileRequest Message queries for the retrieval of file resources

Furthermore, file resource related Resource Adapter (FTP, SSH, LocalFileSystem) can trigger ACS flows. When a file appears in the monitored directory, the Resource Adapter fires an ACS Flow Trigger Event which kicks off the corresponding ACS Flow. Then, the ACS Flow can for example process the triggering resource, put it into a message and transfer it as FileTransfer Message back to back-end messaging system (see Figure 10).

Note: The OSGi Event Admin Trigger Event is the matching key between a resource and the corresponding ACS flow.



Figure 10: Process flow for outbound messages: Existence of monitored file resources triggers ACS Flow which can retrieve the triggering resource and send it to the messaging back-end as FileTransfer Message.

Messages carry JDBC Database Resource Data

The MessagePurpose=DBRecordUpdate is used for accessing JDBC database resources (insert, update and delete of database records; see Figure 11). The transferred data can be SQL statements as well as complete data records provided in an XML file structure.


Figure 11: Process flow for inbound messages with JDBC resource data

Database resources can also be transferred from the remote location to the back-end. Such a transfer can be either initiated by the request messages with MessagePurpose=DBRecordSelect (back-end initiated, see Figure 12) or by the existence of monitored DB Result Sets (local Resource Adapter initiated; see Figure 13).

For the initiation from the back-end, the DBRecordSelect message is used which can contain complete SQL statements for the retrieval of the database resource data or the Expeditor integrator XML structure (<XPDinteg_DBdata_xml_structure>, see chapter 2.5.2 Expeditor integrator XML Data Structure for DB Operations).


Figure 12: Process flow for outbound messages: DBRecordSelect Message queries for the retrieval of database resources.

Similarly to the file resource related Resource Adapters, the JDBC Resource Adapter can monitor for the existence of the result set of a given database querry (database querry is configurable as SQL statement or xpath querry; see Figure 13).


Figure 13: Process flow for outbound messages: JDBC Resource Adapter monitors database by querying it regularly for a configurable result set. If the result set exists, the corresponding ACS Flow is triggered and executed. The flow can sent the triggering result set to the messaging back-end as XML structure.


Please, refer to chapter 2.5 Data Exchange with the JDBC Resource Adapter for details about the JDBC Resource Adapter.

Messages are passed on to other Queues/Topics

The JMS Custom Header property MessagePurpose=MessageForward is used for re-routing of messages from an incoming queue to another local or even remotely bridged queue (see Figure 14).

Typical use cases cover the integration of other local JMS clients into the back-end messaging system. Expeditor integrator bridges local clients, for example self-check-out machines, terminals or handheld devices, into the back-end process flows (see retail example in Figure 1 of chapter 1.2 Solution Overview Example).



Figure 14: Process flow for inbound messages which are further processed and moved to other queues

JMS messages can be transparently routed to other local and remote (bridged) queues and topics. During this message forwarding, Expeditor integrator JMS Custom Header properties can be explicitly set (overwritten, added or deleted; see MessageWrite Activity in section 4).
Please, refer to chapter 4.4.1 Example: Configure Message Forwarding for configuring the Message Forwarding use case.

Messages carry Expeditor integrator Control Information

The Expeditor integrator can also be remotely controlled by defined control and request messages. The following MessagePurpose values are supported (Expeditor integrator control messages):

• FileRequest (for requesting the transmission of a given source file to the back-end from FTP, SSH server or the local file system)
• BrowseDirectory (for retrieving a list of file names of all files in a given FTP, SSH or local file system directory)
• ConfigUpdate (for replacing the existing XPDinteg.xml or the XPDintegRoles.xml file or single configuration properties with a new configuration file or property list in the message’s payload)
• ConfigRetrieval (requests to send the XPDinteg.xml file back to the back-end)
• DrainQueue (for deleting all messages that are currently stored in a given local queue)
• BrowseQueue (for retrieving a list of MessageIds of all messages stored in a give local queue)
• ExecuteScript (for executing a batch file, which is provided in the payload of this message, in a given local file system directory of the Expeditor integrator server)
• Maintenance (for switching Expeditor integrator into Maintenance Mode during which log and business events are not forwarded to the back-end)
• HouseKeeping (for triggering the Housekeeping Flow which takes care of local resources and triggers actions and/or informs the Administrator in case of reached triggers)
• ISACollector (for invoking the IBM Support Assistant which creates a local ZIP file containing required IBM support information)
• PlatformRestart (for re-starting or even stopping the Expeditor integrator runtime)

Messages carry HTTP Resource Data

Figure 15 shows the flow of messages that carry HTTP resources (e.g. files), text, any binary stream (e.g. mp3 file) or even a command (e.g. a form for a servlet or script) from the back-end to the (remote) install location of Expeditor integrator. The destination resource is assembled on the Expeditor integrator and created in the given directory of the target HTTP server by a defined set of ACS Activities. The triggered ACS Flow, Activities and the accessed target resource depend on transport protocol (HTTP or HTTPs), HTTP authentication method and transfered data type (mime type).

The Activity set builds the ACS flow which was configured for processing of defined message types (default or custom flows and activities).

Figure 15: Process flow for inbound messages with HTTP resource data

The JMS Destination Adapter monitors given local queues and topics of the used JMS provider (e.g. Lotus Expeditor micro broker). As soon as a matching resource appears (e.g. a message with MessagePurpose=HttpPut), the configured ACS Flow is triggered through the Flow Trigger Event. Different combination of the JMS Custom Header properties MessagePurpose, TransportType and ResourceType allow for starting different ACS Flows (see supported JMS Custom Header properties in chapter 2.3 JMS Custom Header Properties and 4.4 Resource Adapter configuration in Ref_1).

Figure 16 shows how the Dispatcher Service can be used. It moves messages to other local in queues and also fires ACS Flow Trigger Events. This can be configured and further refined in the inbound Resource Mapper configuration.

Note: The Dispatcher Service is not working in transactional context (“air gap”), but offers distributing of messages to different inbound queues for further parallel processing (faster and recommended for very large message bulks).

Figure 16: Process flow for inbound messages with HTTP resource data using the Dispatcher Service

HTTP Request messages can be sent to Expeditor integrator to query for specific HTTP resource located on HTTP servers. The Request Message contains the resource location in the JMS Custom Header property DestinationPath and DestinationName. TransportType and ResourceType should be provided for further configuration details (ResourceType can also be used to map to a given Resource Mapper configuration in the XPDinteg.xml file).

Figure 17: Process flow for outbound messages: HTTP Request Message queries for the retrieval of HTTP resources

Furthermore, the HTTP Resource can trigger ACS flows. When a resource appears in the monitored directory on the HTTP server, the Resource Adapter fires an ACS Flow Trigger Event which kicks off the corresponding ACS Flow. Then, the ACS Flow can for example retrieve and process the triggering resource, put it into a message and transfer it as FileTransfer Message back to back-end messaging system (see Figure 18).

Note: The OSGi Event Admin Trigger Event is the matching key between a resource and the corresponding ACS flow.

Figure 18: Process flow for outbound messages: Existence of monitored HTTP resources trigger ACS Flow which can retrieve the triggering resource and send it to the messaging back-end as FileTransfer Message.

Supported Custom Header Properties for Inbound Messages

Table 3 contains the supported combination of JMS Custom Header properties for incoming default messages (refer to Figure 7 and Figure 8 for FileTransfer, Figure 9 for FileRequest, Figure 11 for DBRecordUpdate, Figure 12 for DBRecordSelect requests and Figure 14 for MessageForward messages in chapter 2.4.1 JMS Custom Header Creation for Message Transfer between Back-end and Expeditor integrator).

Note: If the Queue Dispatcher Service is used for incoming messages, the JMS Custom Header property LocationId must be provided and must match the value configured in the Expeditor integrator.


Table 3: Supported JMS custom header properties for incoming messages

Message content	Message header paramater values			Additional mandatory properties
	MessagePurpose	TransportType	ResourceType
Data messages
Message carries a file that needs to be send to (4690) FTP Server	FileTransfer	FTP	(header not provided)	DestinationPath & -Name ResourceCmd (here: FtpServer:value1;FtpServerPort:value2;FtpPassive:value3;FtpUser:value4;FtpPassword:value5;FtpType:value6) Please, use the property-value pairs of the XPDinteg.xml FTP properties (e.g. ResourceCmd=FtpServer:192.168.1.2;FtpServerPort:21;FtpPassive:true;FtpUser:test;FtpPassword:test;FtpType:DEFAULT) TransferMode (ASCII | BINARY) DestinationCreationMode (APPEND | OVERWRITE) MessageId, TransactionId, LocationId, MessageSrcId HeaderVersion, SequenceNo, EndOfData, BuildInterval
			FtpFile
		default | (header not provided)	PriceUpdFile	Specific types for retail industry example: All other required properties can be retrieved from the local Expeditor integrator configuration. If they are set in the header anyway, they overwright the local configuration (e.g. the DestinationName of a PriceUpdFile could be changed this way)
			MappingDataFile
			DiscountDataFile
Message carries a file that needs to be send to SSH Server	FileTransfer	SSH	(header not provided)	DestinationPath & -Name ResourceCmd (here: SshServer:value1;SshServerPort:value2;SshUser:value4;SshPassword:value5; SshType:value6) Please, use the property-value pairs of the XPDinteg.xml FTP properties (e.g. ResourceCmd=SshServer:192.168.1.2;SshServerPort:21;SshUser:test;SshPassword:test;SshType:SFTP) TransferMode (ASCII | BINARY) DestinationCreationMode (APPEND | OVERWRITE) MessageId, TransactionId, LocationId, MessageSrcId HeaderVersion, SequenceNo, EndOfData, BuildInterval
			SshFile
Message carries a file that needs to be detached to the Local File System	FileTransfer	LocalFileSystem	(header not provided)	DestinationPath & -Name TransferMode (ASCII | BINARY) DestinationCreationMode (APPEND | OVERWRITE) MessageId, TransactionId, LocationId, MessageSrcId HeaderVersion, SequenceNo, EndOfData, BuildInterval
			LocalFileSystemFile
		LocalFileSystem | default | (header not provided)	ScaleDataFile	Retail industry example: All other required properties should be retrieved from the local Expeditor integrator configuration. If they are set in the header anyway, they overwrite the local configuration (e.g. the DestinationName of a PriceUpdFile could be changed this way)
			PrintLabelFile
			ShelfLabelFile
Message carries a request to send a distinct file back to the AI back-end	FileRequest	FTP	anything | (header not provided)	ResourceType is set to default value = FtpFile DestinationPath & -Name TransferMode (ASCII | BINARY) ResourceCmd (here: FtpServer:value1;FtpServerPort:value2;FtpPassive:value3;FtpUser:value4;FtpPassword:value5;FtpType:value6) Please, use the property-value pairs of the XPDinteg.xml FTP properties (e.g. ResourceCmd=FtpServer:192.168.1.2;FtpServerPort:21;FtpPassive:true;FtpUser:test;FtpPassword:test;FtpType:DEFAULT) TransferConfirmationMode (NONE | OVERWRITE | RecreateZero | WriteOtherFile) (-WriteOtherFileName if TransferConfirmationMode=WriteOtherFile) HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId
		SSH		(see FTP) ResourceCmd (here: SshServer:value1;SshServerPort:value2;SshUser:value4;SshPassword:value5; SshType:value6) Please, use the property-value pairs of the XPDinteg.xml FTP properties (e.g. ResourceCmd=SshServer:192.168.1.2;SshServerPort:21;SshUser:test;SshPassword:test;SshType:SFTP)
		LocalFileSystem		ResourceType is set to default value = LocalFileSystemFile DestinationPath & -Name TransferMode (ASCII | BINARY) TransferConfirmationMode (NONE | OVERWRITE | RecreateZero | WriteOtherFile) (-WriteOtherFileName if TransferConfirmationMode=WriteOtherFile) MessageId, TransactionId, LocationId, MessageSrcId
		anything	PriceUpdFile | MappingDataFile | DiscountDataFile | ScaleDataFile | PrintLabelFile | ShelfLabelFile	Retail industry example: All other required properties including the TransportType should be retrieved from the local Expeditor integrator configuration. If they are set in the header anyway, they overwrite the local configuration (e.g. the DestinationName of a PriceUpdFile could be changed this way)
Message carries a database record that needs to be written	DBRecordUpdate	DB | anything | (header not provided)	anything | (header not provided)	Maps to an INSERT SQL statement DestinationPath (DB URI and DRIVER_CLASS) (DestinationPath=DB_URI:’<database_URI>’;DRIVER_CLASS:’<DRIVER_CLASS>’ e.g. DestinationPath= DBURI:’jdbc:derby:d:/workspace/SampleDb;create=TRUE’;DRIVER_CLASS:’org.apache.derby.jdbc.EmbeddedDriver’ DestinationName (DB Table) ResourceCmd={SQL | XPDINTEG_DBXML | XML} DestinationCreationMode (INSERT | UPDATE | TABLE_CREATE | UPDATE_INSERT) MessageId, TransactionId, LocationId, MessageSrcId HeaderVersion, SequenceNo, EndOfData, BuildInterval Credentials=User:<db_user>;Password:<db_password> TransferConfirmationMode= { NONE | DELETE | SQL:SQLStmt }, NONE – don’t do anything with the record which triggered the flow, DELETE - SQL delete for records in the result set which triggered this flow only, SQL – provide own SQL statement, where SQLStmt=select * from table2 where x=? and y=? OR SQLStmt=select * from <trigger_rec_column1> where x=<trigger_rec_column2> and y=<trigger_rec_column3> payload contains SQL statements separated by semicolon, XPDINTEG_DBXML format or custom XML format see chapter 2.5 Data Exchange with the JDBC Resource Adapter
Message carries a SQL command for retrieving a distinct database record	DBRecordSelect	DB | anything | (header not provided)	anything | (header not provided)	Maps to an SELECT SQL statement DestinationPath (DB URI and DRIVER_CLASS) (DestinationPath=DB_URI:’<database_URI>’;DRIVER_CLASS:’<DRIVER_CLASS>’) e.g. DestinationPath= DBURI:’jdbc:derby:d:/workspace/SampleDb;create=TRUE’;DRIVER_CLASS:’org.apache.derby.jdbc.EmbeddedDriver’ DestinationName (DB Table) ResourceCmd={SQL | XPDINTEG_DBXML | XML} MessageId, TransactionId, LocationId, MessageSrcId HeaderVersion, SequenceNo, EndOfData, BuildInterval Credentials=User:<user>;Password:<password> TransferConfirmationMode= { NONE | DELETE | SQL:SQLStmt }, NONE – don’t do anything with the record which triggered the flow, DELETE - SQL delete for records in the result set which triggered this flow only, SQL – provide own SQL statement, where SQLStmt=select * from table2 where x=? and y=? OR SQLStmt=select * from @nowiki@20where x=<trigger_rec_column2> and y=<trigger_rec_column3> payload contains SQL statements separated by semicolon, XPDINTEG_DBXML format or custom XML format see chapter 2.5 Data Exchange with the JDBC Resource Adapter
Message carries another message which is moved from one local queue to another local queue	MessageForward	MESSAGE | anything | (header not provided)	anything | (header not provided)	This applies to incoming messages at the default ReqInQ (using the Queue Dispatcher). If not provided, ResourceType is set to default value = Message and TransportType=MESSAGE DestinationName (JNDI key of local destination queue provided in message header property, Resource Mapper or MessageWrite Activity context parameter) HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId Note: Other local queues can also be used for sending and receiving messages. Then, these parameters are not mandatory.
Control messages Optionally, all flows can be secured by the CheckJMSHeaderPropertyActivitiy. This Activity can be used to check the Credentials property values of the requesting message: Credentials=User:<user>;Password:<password>
Message requests a file listing of a given file directory	BrowseDirectory	FTP	--	ResourceType is not used DestinationPath ResourceCmd (here: ftpServer:value1;ftpServerPort:value2;ftpPassive:value3;ftpUser:value4;ftpPassword:value5;ftpType:value6) Please, use the property-value pairs of the XPDinteg.xml FTP properties (e.g. ResourceCmd=FtpServer:192.168.1.2;FtpServerPort:21;FtpPassive:true;FtpUser:test;FtpPassword:test;FtpType:DEFAULT) HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId
		SSH		(see FTP) ResourceCmd (here: SshServer:value1;SshServerPort:value2;SshUser:value4;SshPassword:value5; SshType:value6) Please, use the property-value pairs of the XPDinteg.xml FTP properties (e.g. ResourceCmd=SshServer:192.168.1.2;SshServerPort:21;SshUser:test;SshPassword:test;SshType:SFTP)
		LocalFileSystem		ResourceType is not used DestinationPath MessageId, TransactionId, LocationId, MessageSrcId
Message carries a new XPDinteg.xml file with config changes OR a list of updated Expeditor integrator properties	ConfigUpdate	-	ConfigurationUpdateFile	ResourceType is set to ConfigurationUpdateFile HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId Message payload contains new XPDinteg.xml file or XPDINTEG_CONFIG_XML structure ResourceCmd={FILE | ParamList};Command:{restart | stop } [; Param:{ console,reset } ]
Message carries a new XPDintegRoles.xml file with config changes OR a list of updated User Admin store properties	ConfigUpdate	-	UserConfigUpdateFile	ResourceType is set to UserConfigUpdateFile HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId Message payload contains new XPDintegRoles.xml file or XPDINTEG_USERROLES_XML structure ResourceCmd={UserConfigFILE | UserConfigParamList};Command:{restart | stop }[; Param:{ console,reset } ]
Message carries a request to delete all messages in a distinct local queue	DrainQueue	-	- (jndiDestinationKey of queue must be provided in JMS header property DestinationName)	TransportType and ResourceType is not used DestinationName (jndiDestinationKey of queue) HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId Recommended: Credentials=User:<user>;Password:<password>
Message requests the list of IDs of all message that are currently stored in a distinct local queue back to the AI	BrowseQueue	-	-	TransportType and ResourceType are not used DestinationName (jndiDestinationKey of queue) HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId
Message carries a batch that needs to be detached to local directory and executed OR Message requests the execution of an existing local script	ExecuteScript	-	- (DestinationPath & -name must be provided in the JMS header)	ResourceType is set to LocalFileSystemFile DestinationPath & -Name (Location to which script is detached if transferred in the payload.) The file under this location is executed (could also be an existing file). DestinationCreationMode (APPEND | OVERWRITE) HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId Recommended: Credentials=User:<user>;Password:<password>
Message carries a request to retrieve the XPDinteg configuration	ConfigRetrieval	-	-	TransportType and ResourceType are not used HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId Recommended: Credentials=User:<user>;Password:<password>
Message carries a request to update the Maintenance mode	Maintenance	-	-	HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId ResourceCmd={ON | OFF} [;Command:{restart | stop}; Param:{console,reset} ] Recommended: Credentials=User:<user>;Password:<password>
Message carries a request to start HouseKeeping	HouseKeeping	-	-	HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId
Message carries request to re-start or stop the platform	PlatformRestart	-	-	HeaderVersion, MessageId, TransactionId, LocationId, MessageSrcId ResourceCmd=Command:{restart | stop} [;Param:{ console,reset } ] Strongly recommended: Credentials=User:<user>;Password:<password>
Message that is not routable	unknown	anything | (header not provided)	anything | (header not provided)

Note: It also recommended to provide the TimeStamp (creation time of the message) and the TTL (Time-to-Live) properties. These are required for the Housekeeping operation of Expeditor integrator.

JMS Custom Header Creation for Messages from Expeditor integrator to Back-end (outbound)

There are use cases that require the Expeditor integrator to react by sending messages to the back-end Message Broker (e.g. BUC_2-Transaction Data Transfer; File Transfer from FTP Server). Data for other systems is packaged into messages with message headers which identify the message purpose and the message content (refer to Figure 10 for file resources and Figure 13 for database resources in chapter 2.4.1JMS Custom Header Creation for Message Transfer between Back-end and Expeditor integrator ).

Table 4 gives an overview of the currently supported (response) JMS custom message headers that are created by the Expeditor integrator. The MessageId is a unique ID for each created message and follows the

The <static_counter> is an application wide static counter that is increased by +1 for each created message to ensure unique Message IDs.
If an Expeditor integrator ACS flow is triggered by incoming message which is running within another transactional context and therefore, carries a unique TransactionId, this TransactionId is maintained and used to identify the locally triggered ACS flow on the Expeditor integrator runtime. If the TransactionId is not provided by the triggering resource (e.g. message) or the ACS flow is triggered locally, the TransactionId is also uniquely created and follows the same Expeditor integrator schema for unique IDs (as the MessageId):


Basic rules:

• ResourceType is set to the ResourceType provided in the request message. If a file is captured that is not known yet, then ResourceType is set to the default value = FtpFile | LocalFileSystemFile | SshFile | DBResource | Message depending on the TransportType.
  
  
• TransactionId is set to the TransactionId of the request message. If this is not available, because it was not provided in the request message or the ACS flow was triggered locally, it is uniquely set to TransactionId := <LocationId>_<date/time_stamp_in_long>_<static_counter>
  
  
• Incoming messages which are transparently forwarded (see MessageForward use cases) will maintain their original MessageId value if this was included in the incoming message (as Expeditor integrator JMS custom header property MessageId). For all other locally created messages, the created MessageId is uniquely set to MessageId := <LocationId>_<date/time_stamp_in_long>_<static_counter>
  
  
• MessagePriority is set to the value in the Expeditor integrator configuration (property TransferPriority) or to 0 if TransferPriority is not available (not in request message nor local configuration). It is mapped to the standard JMS message priority and is used by the JMS handlers. Messages with the highest priority are processed first (possible values: 0-9; [0]-lowest, [9]-highest).
  
  
• The JMS message priority is set to the MessagePriority custom header property.
  
  
• SequenceNo is created according to Table 12 in chapter 3.1Transfer of large files in multiple messages (single message: SequenceNo=0, sequence of multiple messages: SequenceNo=1..n)

Figure 19 shows the flow of messages that carry files, file content or fragments of files from the back-end to the Expeditor integrator (e.g. retail store server). The destination file is assembled and created in the given target directory by a defined set of Activities. The Activity set builds the Application Control Flows (ACS) flow that was configured for the processing of certain message types.



Figure 19: Process flow for outbound messages with file resource data (BUC_2)


Figure 13 for database resources in chapter 2.4.1JMS Custom Header Creation for Message Transfer between Back-end and Expeditor integrator explains how database are monitored and transferred to the messaging back-end or other messaging providers.

Table 4 provides all currently supported JMS custom header property combinations for locally created messages.

Note: These Expeditor integrator JMS custom message headers are created by the XPDINTEG_MESSAGE_WRITE activity within ACS Flows (see chapter 4.1.3 ACS Activities). The values for the custom header properties are retrieved from the available flow context information. This information is based on JMS custom message headers of the message that triggered the flow, information from the Resource Mapper or from the activity/flow context. The information provided in the JMS header of the triggering/incoming message and its extension in the Resource Mapper has highest priority. The context parameters in the activity/flow can only overwrite the activity settings given in the Application Control Service configuration section of the XPDinteg.xml. However, the XPDINTEG_MESSAGE_WRITE activity provides the opportunity to add, delete and overwrite existing JMS Custom header and Resource Mapper properties (see Table 27 in chapter 4.1.3 ACS Activities). If no Expeditor integrator related JMS custom message header property information is available in the flow context, the option

…allows adding the following Expeditor integrator Default JMS Custom Message Header Properties (default is TRUE):

• If values are available in the activity/flow context:
• MessagePurpose:{MessageForward|<given_message_purpose>
• TransportType:{MESSAGE|<given_transport_type>}
• ResourceType:{Message|customer_value}
• TTL:<taken_from_incoming_message_if_provided>
  
  
• Values created by Expeditor integrator:
• Encoding:<encoding>
• TransferMode:{ASCII|BINARY}
• HeaderVersion:{<2.0> | <taken_from_local_configuration>}
• MessageId:{<LocationId>_<date/time_stamp_in_long>_<static_counter> | <MessageId_of_forwarded_message>}
• TransactionId:{<TransactionId_of_triggering_message> | <LocationId>_<date/time_stamp_in_long>_<static_counter>}
• EndOfData:{true|false}
• SequenceNo:<sequence_no>
• LocationId:<LocationId>
• DestinationName:<jndi_key_of_target_queue>
• MessagePriority:<TransferPriority_of_properties> (JMS Message priority:<MessagePriority>)
• ResourceSize:<size_of_data_in_payload>
• TimeStamp:<creation_time_of_message>
• MessageSrcId:<Expeditor_integrator_hostname>

Table 4: JMS Custom header properties of messages created by the Expeditor integrator

Use Case	Example for JMS Custom Header for Reply	Comments
General Resource data transfer from back-end to Expeditor integrator
Data transfer from back-end to integrator (back-end initiated)	No reply data message (MessagePurpose examples of back-end message: FileTransfer, DBRecourdUpdate, MessageForward)	messages from back-end carry data for locally attached resources (e.g. FileTransfer, DBRecordUpdate; see BUC_1 / BUC_3). Business and Log Events are available for monitoring the process.
FTP related use cases
Data transfer from integrator to back-end (initiated by resource existence)	ResourceType:<FtpFile> Encoding:UTF-8 TransferMode:BINARY MessagePurpose:FileTransfer TransportType:FTP HeaderVersion:<2.0> | <version_set_in_config> MessageId:<LocationId>_<date/time_stamp_in_long>_<static_counter> TransactionId: <LocationId>_<date/time_stamp_in_ long>_<static_counter> EndOfData:true SequenceNo:0 LocationId:Store100 DestinationPath:<DestinationPath_from_local_config> DestinationName:<DestinationName_from_local_config> MessagePriority:<TransferPriority_from_ local_config> (JMS Message priority:MessagePriority) ResourceSize:<size_of_file_in_payload> TimeStamp:<creation_time_of_file> MessageSrcId:<XPDinteg_hostname>	File existence in monitored directory triggers file transfer (see BUC_2): If a file is captured that is not configured in Resource Mapper in XPDinteg.xml yet, then ResourceType is set to the default value = FtpFile. Retail example: ResourceType=PosTransDataFile1 The Encoding property is only valid when TransferMode is set to ASCII. TransactionId is uniquely set according to Expeditor integrator ID schema. MessagePriority is set to the value in the Expeditor integrator configuration store (property TransferPriority) or to 0 if TransferPriority is not available. The JMS message priority is set to the value of the MessagePriority custom header property (values 0-9; [0]-lowest, [9]-highest). Values for the DestinationPath and -Name properties are taken from the local Expeditor integrator configuration. In case of BUC_2 the MetaData (XPDinteg.xml file) contains the file information to be monitored. This value is split into two parts (directory name and file name) and set as the DestinationPath and DestinationName.
Data transfer from integrator to back-end (back-end triggers resource transfer)	ResourceType:<FtpFile> Encoding:UTF-8 TransferMode:ASCII MessagePurpose:FileRequest TransportType:FTP HeaderVersion:<2.0> | <version_set_in_config> MessageId:<LocationId>_<date/time_stamp_in_long>_<static_counter> TransactionId:{<TransactionId_of_reqMsg> | <LocationId>_<date/time_stamp_in_ long>_<static_counter>} EndOfData:true SequenceNo:0 LocationId:Store100 DestinationPath:<DestinationPath_of_reqMsg> DestinationName:<DestinationName_of_reqMsg> MessagePriority:<TransferPriority_of_reqMsg> (JMS Message priority:MessagePriority) ResourceSize:<size of file_in_payload> TimeStamp:<creation_time_of_file> MessageSrcId:<XPDinteg_hostname>	Message requests file transfer ResourceType is set to the ResourceType provided in the request message. If a file is captured that is not know yet, the ResourceType is set to the default value = FtpFile. The Encoding property is only valid when TransferMode is set to ASCII. TransactionId is set to the TransactionId of the request message. If this is not available, it is uniquely set according to Expeditor integrator ID schema. MessagePriority is set to the TransferPriority in the request message. If not set, the default value = 0 is used. Values for the DestinationPath and -Name properties are taken from the aquivalent JMS custom header properties or if the ResourceType is known from the local configuration. The JMS message priority is set to the MessagePriority custom header property value (possible values: 0-9; [0]-lowest, [9]-highest).
File System related use cases
Data transfer from integrator to back-end (initiated by resource existence)	ResourceType:<LocalFileSystemFile> Encoding: UTF-8 TransferMode: ASCII MessagePurpose: FileTransfer TransportType: LocalFileSystem HeaderVersion:<2.0> | <version_set_in_config> MessageId:<LocationId>_<date/time_stamp_in_long>_<static_counter> TransactionId:<LocationId>_<date/time_stamp_in_ long>_<static_counter> EndOfData:true SequenceNo: 0 LocationId:Store100 DestinationPath:<DestinationPath_from_local_config> DestinationName:<DestinationName_from_local_config> MessagePriority:<TransferPriority_of_properties> (JMS Message priority:<MessagePriority>) ResourceSize:<size_of_file_in_payload> TimeStamp:<creation_time_of_file> MessageSrcId:<XPDinteg_hostname>	File appearance triggers file transfer If a file is captured that we are not know yet, the ResourceType is set to the default value = LocalFileSystemFile. The Encoding paramter is only valid when TransferMode is set to ASCII. TransactionId is uniquely set according to Expeditor integrator ID schema. MessagePriority is set to the value in the Expeditor integrator configuration store (property TransferPriority) or to 0 if TransferPriority is not available. Values for the DestinationPath and -Name properties are taken from the local Expeditor integrator configuration. The MetaData value is split into two parts (directory name and file name) and set as the DestinationPath and DestinationName. The JMS message priority is set to the value of the MessagePriority custom header property (possible values: 0-9; [0]-lowest, [9]-highest).
Data transfer from integrator to back-end (back-end triggers resource transfer)	ResourceType:<LocalFileSystemFile> Encoding:UTF-8 TransferMode:ASCII MessagePurpose: FileRequest TransportType:LocalFileSystem HeaderVersion:<2.0> | <version_set_in_config> MessageId:<LocationId>_<date/time_stamp_in_long>_<static_counter> TransactionId:{<TransactionId_of_reqMsg> | <LocationId>_<date/time_stamp_in_ long>_<static_counter>} EndOfData:true SequenceNo:0 LocationId:Store100 DestinationPath:<DestinationPath_of_requMsg> DestinationName:<DestinationName_of_reqMsg> MessagePriority:<TransferPriority_of_reqMsg> (JMS Message priority:<MessagePriority>) ResourceSize:<size_of_file_in_payload> TimeStamp:<creation_time_of_file> MessageSrcId:<XPDinteg_hostname>	Message requests file transfer ResourceType is set to the ResourceType provided in the request message. If a file is captured that we are not know yet, the ResourceType is set to the default value = LocalFileSystemFile. The Encoding paramter is only valid when TransferMode is set to ASCII. TransactionId is set to the TransactionId of the request message. If this is not available, it is uniquely set according to Expeditor integrator ID schema. Values for the DestinationPath and -Name properties are taken from the aquivalent JMS custom header properties or if the ResourceType is known from the local configuration. MessagePriority is set to the TransferPriority in the request message. If this is not set, the default value = 0 is used. The JMS message priority is set to the value of the MessagePriority custom header property (possible values: 0-9; [0]-lowest, [9]-highest).
Database resource related use cases
Data transfer from integrator to back-end (initiated by resource existence)	ResourceType:<DBResource> Encoding: UTF-8 TransferMode: ASCII MessagePurpose: DBRecordSelect TransportType: DB HeaderVersion:<2.0> | <version_set_in_config> MessageId:<LocationId>_<date/time_stamp_in_long>_<static_counter> TransactionId: <LocationId>_<date/time_stamp_in_ long>_<static_counter> EndOfData:true SequenceNo:0 LocationId:Store100 DestinationPath:DBURI:’<database_URI>’;DRIVER_CLASS:’<DRIVER_CLASS>’ DestinationName:<table_name> TransferConfirmationMode= <NONE | DELETE | SQL:SQLStmt> MessagePriority:<TransferPriority_of_properties> (JMS Message priority:<MessagePriority>) ResourceSize:<size_of_xml_file_in_payload> TimeStamp:<creation_time_of_file> MessageSrcId:<XPDinteg_hostname> Message Payload:<XPDinteg_DBdata_xml_structure>	Database result set appearance triggers data transfer. If a DB result set is captured that is not known yet, the ResourceType is set to the default value = DBResource. The Encoding property is only valid when TransferMode is set to ASCII. TransactionId is uniquely set according to Expeditor integrator ID schema. MessagePriority is set to the value in the Expeditor integrator configuration store (property TransferPriority) or to 0 if TransferPriority is not available. Values for the DestinationPath and -Name properties are taken from the local Expeditor integrator configuration (Resource Adapter, Resource Mapper or DB Activities). e.g. DestinationPath= DBURI:’jdbc:derby:d:/workspace/SampleDb;create=TRUE’;DRIVER_CLASS:’org.apache.derby.jdbc.EmbeddedDriver’ DestinationName (DB Table) ResourceCmd={SQL | XPDINTEG_DBXML | XML} contains the database action that was executed. TransferConfirmationMode= { NONE | DELETE | SQL:SQLStmt }, NONE – don’t do anything with the record which triggered the flow, DELETE - SQL delete for records in the result set which triggered this flow only, SQL – provide own SQL statement, where SQLStmt=select * from table2 where x=? and y=? OR SQLStmt=select * from <trigger_rec_column1> where x=<trigger_rec_column2> and y=<trigger_rec_column3> The JMS message priority is set to the value of the MessagePriority custom header property (possible values: 0-9; [0]-lowest, [9]-highest). By default, messages of ResourceType=DBResource carry the DB query’s result set as well defined XML structure (XML v1.1 file) in the message payload (see XPDinteg_DBdata_simplexml_structure and XPDinteg_DBdata_xml_structure in chapter 2.5.2 Expeditor integrator XML Data Structure for DB operations).
Data transfer from integrator to back-end (back-end triggers resource transfer)	ResourceType:<DBResource> Encoding:UTF-8 TransferMode:ASCII MessagePurpose: DBRecordSelect TransportType:DB HeaderVersion:<2.0> | <version_set_in_config> MessageId:<LocationId>_<date/time_stamp_in_long>_<static_counter> TransactionId:{<TransactionId_of_reqMsg> | <LocationId>_<date/time_stamp_in_ long>_<static_counter>} EndOfData:true SequenceNo:0 LocationId:Store100 DestinationPath:<DestinationPath_of_requMsg> DestinationName:<DestinationName_of_reqMsg> ResourceCmd=<SQL | XPDINTEG_DBXML | XML> MessagePriority:<TransferPriority_of_reqMsg> (JMS Message priority:<MessagePriority>) ResourceSize:<size_of_xml_file_in_payload> TimeStamp:<creation_time_of_file> MessageSrcId:<XPDinteg_hostname> Message Payload: <XPDinteg_DBdata_xml_structure>	Message requests transfer of database result set. ResourceType is set to the ResourceType provided in the request message. If a database resource is captured that is not known yet, the ResourceType is set to the default value = DBResource. The Encoding property is only valid when TransferMode is set to ASCII. TransactionId is set to the TransactionId of the request message. If this is not available, it is uniquely set according to Expeditor integrator ID schema. Values for the DestinationPath and -Name properties are taken from the local Expeditor integrator configuration (Resource Adapter, Resource Mapper or DB Activities). (DestinationPath=DB_URI:’<database_URI>’;DRIVER_CLASS:’<DRIVER_CLASS>’) e.g. DestinationPath= DBURI:’jdbc:derby:d:/workspace/SampleDb;create=TRUE’;DRIVER_CLASS:’org.apache.derby.jdbc.EmbeddedDriver’ DestinationName (DB Table) ResourceCmd={SQL | XPDINTEG_DBXML | XML} contains the database action that was executed. MessagePriority is set to the TransferPriority in the request message. If this is not set, the default value = 0 is used. The JMS message priority is set to the value of the MessagePriority custom header property (possible values: 0-9; [0]-lowest, [9]-highest). By default, messages of ResourceType=DBResource carry the DB query’s result set as well defined XML structure (XML v1.1 file) in the message payload (see XPDinteg_DBdata_simplexml_structure and XPDinteg_DBdata_xml_structure in chapter 2.5.2 Expeditor integrator XML Data Structure for DB Operations ).
Message to message related use cases
Data transfer from integrator to back-end (initiated by resource existence)	ResourceType:<Message> Encoding: UTF-8 TransferMode: ASCII MessagePurpose: MessageForward TransportType: MESSAGE HeaderVersion:<2.0> | <version_set_in_config> MessageId:{<MessageId_of_forwarded_msg> | <LocationId>_<date/time_stamp_in_long>_<static_counter>} TransactionId:{<TransactionId_of_forwarded_msg> | <LocationId>_<date/time_stamp_in_ long>_<static_ counter>} EndOfData:true SequenceNo:0 LocationId:Store100 DestinationName:<jndi_key_of_queue> MessagePriority:<TransferPriority_of_properties> (JMS Message priority:<MessagePriority>) ResourceSize:<size_of_data_in_payload> TimeStamp:<creation_time_of_file> TTL:<TTL_of_forwarded_msg> MessageSrcId:<MessageSrcId_of_forwarded_msg> | <XPDinteg_hostname>	Message appearance in local queue triggers data transfer. If a message is found that is not known yet, the ResourceType is set to the default value = Message. The Encoding property is only valid when TransferMode is set to ASCII. MessageId is the MessageId of the forwarded message. If no MessageId custom property is provided, the MessageId is locally created using the Expeditor integrator ID schema. TransactionId is the TransactionId of the forwarded message which is forwarded. If no TransactionId is provided, it is uniquely set according to Expeditor integrator ID schema. MessagePriority is set to the value in the Expeditor integrator configuration store (property TransferPriority) or to 0 if TransferPriority is not available. Values for the DestinationName property contains the JNDI key of the queue and is taken from the local Expeditor integrator configuration (Resource Adapter, Resource Mapper, MsgWriteActivity). The JMS message priority is set to the value of the MessagePriority custom header property (possible values: 0-9; [0]-lowest, [9]-highest). MessageSrcId is set to the one in the forwarded message. If not provided, the hostname of the Expeditor integrator runtime will be used.
Other use cases
Platform control use cases (Control Messages)
Back-end sends Browse Directory control message	ResourceType:not_set Encoding:UTF-8 TransferMode:ASCII MessagePurpose: BrowseDirectory TransportType:FTP | SSH | LocalFileSystem HeaderVersion:<2.0> | <version_set_in_config> MessageId:<LocationId>_<date/time_stamp_in_long>_<static_counter> TransactionId:{<TransactionId_of_reqMsg> | <LocationId>_<date/time_stamp_in_ long>_<static_counter>} EndOfData:true SequenceNo:0 LocationId:Store100 DestinationPath:<DIRPATH=DestinationPath_of_reqMsg> MessagePriority:<TransferPriority_of_reqMsg> (JMS Message priority:MessagePriority) TimeStamp:<creation_time_of_dir_listing> MessageSrcId:<XPDinteg_hostname>	Message requests directory listing ResourceType is not used. TransactionId is set to the TransactionId of the request message. If this is not available, it is uniquely set according to Expeditor integrator ID schema. MessagePriority is set to the TransferPriority in the request message. If it is not set, the default value = 0 is used. The JMS message priority is set to the value of the MessagePriority custom header property (possible values: 0-9; [0]-lowest, [9]-highest).
Back-end sends Browse Queue control message	ResourceType: not set Encoding:UTF-8 TransferMode:ASCII MessagePurpose: BrowseQueue TransportType:Message HeaderVersion:<2.0> | <version_set_in_config> MessageId:<LocationId>_<date/time_stamp_in_long>_<static_counter> TransactionId:{<TransactionId_of_reqMsg> | <LocationId>_<date/time_stamp_in_ long>_<static_counter>} EndOfData:true SequenceNo:0 LocationId:Store100 DestinationName:< jndiDestinationKey_of_queue =DestinationName_of_reqMsg> MessagePriority:<TransferPriority_of_reqMsg> (JMS Message priority:MessagePriority) TimeStamp:<creation_time_of_queue_listing> MessageSrcId:<XPDinteg_hostname>	Message requests queue content listing (listing of message IDs) ResourceType is not used. TransactionId is set to the TransactionId of the request message. If this is not available, it is uniquely set according to Expeditor integrator ID schema. MessagePriority is set to the TransferPriority in the request message. If this is not set, the default value = 0 is used. The JMS message priority is set to the value of the MessagePriority custom header property (possible values: 0-9; [0]-lowest, [9]-highest).
Back-end sends control message	No Reply for control messages with MessagePurpose: DrainQueue, ConfigUpdate, ExecuteScript, Maintenance, HouseKeeping, PlatformRestart	Business and Log Events are available for monitoring the process. Log Event (using the TransactionId; if not available, the MessageId of the request message) is fired after the control flow was executed successfully by the ACS.

Data Exchange with the JDBC Resource Adapter

The JDBC Resource Adapter allows for accessing database resources using JDBC driver Java classes. This adapter can be used…:

• …to monitor JDBC accessible resources. If matching result sets are found trigger events are published which can kick off ACS Flows for further data processing.
• …to read data from and write data to JDBC resources. SQL command(s) can be sent through messages to the Expeditor integrator runtime which are executed on a given JDBC resource. XML-based data can also be transmitted by the JDBC Adapter.

Please, refer to chapter 2.4.1.2 Messages carry JDBC Database Resource Data for an introduction to possible Expeditor integrator JDBC resource access use cases.

Supported Data Formats for JDBC Resource Access

Data for JDBC resources can be handed over to the JDBC Resource Adapter in different formats. The supported formats are specified in the JMS Custom Header property:

The ResourceCmd defines the way of the creation of the SQL command which needs to be executed.

• SQL – the message payload contains complete valid SQL statements that are transparently passed on to the database. The provided SQL statement must be a valid SQL script (SQL commands separated by ‘;’). The SQL CONNECT and DISCONNECT must not be included since these are created during the Java DB connection. The single SQL commands are passed on as prepared statements.
  
  
• XPDINTEG_DBXML– the message payload contains the specific Expeditor integrator database XML structure <XPDinteg_DBdata_xml_structure> which contains SQL command section and data section (see Listing 4 in chapter 2.5.2 Expeditor integrator XML Data Structure for DB Operations). The same XML format is used for the ResultSet which is sent back in a message (ACS Activity: DatabaseSerializationActivcity, see chapter 4.1.3 ACS Activities).
  
  
• XML – The message payload contains a standard XML document with the standard XML header:
  <?xml version="1.0" encoding="UTF-8"?>…
  This carries the data to be updated in the database. The Activity context parameters include the SQL (update) statement as well as the columns which need to be selected from the XML document as XPath statements. Example below:

Listing 3: Example configuration for INSERT and UPDATE cases in the MessageToDBXMLActivity (refer to Activity catalogue in chapter 4.1.3 ACS Activities)

Expeditor integrator XML Data Structure for DB Operations

The database command can be provided in the MessagePurpose=DBRecordUpdate/DBRecordSelect message as complete sequence of SQL statements (ResourceCmd = SQL) or in the <database-command> section of the Expeditor integrator specific XML structure XPDinteg_DBdata_xml_structure (ResourceCmd = XPDINTEG_DBXML, see Listing 4).

Listing 4: XPDinteg database data and result set structure XPDinteg_DBdata_xml_structure


Note: The XPDinteg_DBdata_xml_structure must be escaped when it is included in the <text> tag of an XML message (see example messages in APPENDIX A – Example Messages).

Retrieved Datbase ResultSets (DatabaseResourceData object) can also be transformed into the XPDinteg_DBdata_xml_structure for further processing, e.g. putting as payload into result messages. The Application Control Flow DatabaseSerializationActivity offers options for creating result set XML structures of:

• XPDinteg_DBdata_xml_structure or
• XPDinteg_DBdata_simplexml_structure.

The XPDinteg_DBdata_simplexml_structure is the default format delivered by the DbSerialization Activity and lists all records of the result separated by @nowiki@63property sections as simple XML structure (see Listing 5 and DatabaseSerializationActivity in Table 27).


Listing 5: XPDinteg_DBdata_simplexml_structure created by the DbSerialization Activity (Format=”SIMPLE_XML”).


An example for XPDinteg_DBdata_simplexml_structure is given in Listing 6.


Listing 6: Example XML result set in XPDinteg_DBdata_simplexml_structure created by the DatabaseSerializationActivity when Format=”SIMPLE_XML” (SQL statement = SELECT * FROM menu).


Datatypes
The XPDinteg_DBdata_xml_structure understands Java data types. These are mapped to SQL data types appropriately (see mapping documentation in http://java.sun.com/j2se/1.3/docs/guide/jdbc/getstart/mapping.html ). The following types are supported in XPDinteg_DBdata_xml_structure:

Table 5: Supported types in XPDinteg_DBdata_xml_structure

Java basic type in XPDinteg_DBdata_xml_structure	SQL type	Comment
String, Int, double	Regarding to http://java.sun.com/j2se/1.3/docs/guide/jdbc/getstart/mapping.html
Expr	depends on the values provided	Data field contains other variables,e.g. ‘PRICE+0.5’
BLOB, CLOB	BLOB, CLOB	(not implemented )

DBRecordUpdate Messages

Message Header Properties

The following Custom Message Header properties are available for messages sent from back-end messaging system to Expeditor integrator runtime (see Table 3 in chapter 2.4.2 Supported Custom Header Properties for Inbound Messages also):

• DestinationPath=DBURI:’<uri_name>’;DRIVER_CLASS:’<driver_class_path_and_name>’
  (names contain forward slashes only!)
  
  Example for Derby: DBURI:’jdbc:derby:datatrans/inbound/SampleDb;create=true’;DRIVER_CLASS:’org.apache.derby.jdbc.EmbeddedDriver’
  
  Example for DB2: DBURI:’jdbc:db2://localhost:50000/SampleDb’;DRIVER_CLASS:’com.ibm.db2.jcc.DB2Driver’
  
  
• DestinationName=<db_table_name>
• Credentials=User:<DbUser>;Password:<DbPassword>
• ResourceCmd=SQL | XPDINTEG_DBXML | XML
• SQL – message payload contains SQL command as a string
• XPDINTEG_DBXML – message payload contains <XPDinteg_DBdata_xml_structure> (see Listing 4 in chapter 2.5.2 Expeditor integrator XML Data Structure for DB Operations)
• XML - The message payload contains a standard XML document with the standard XML header: <?xml version="1.0" encoding="UTF-8"?>…
  (see chapter 2.5.1 Supported Data Formats for JDBC Resource Access)
  
  
• DestinationCreationMode=TABLE_CREATE | INSERT | UPDATE | UPDATE_INSERT
• TABLE_CREATE – table is created if not existent
• TABLE_DROP – removes table if it exists
• UPDATE - SQL update (fails if record does not exist)
• INSERT – SQL insert (fails if record exists)
• UPDATE_INSERT – SQL read ahead, if record exists then update it / if record does not exist then insert it
• Payload={string_of_full_sql_statement | <XPDinteg_DBdata_xml_structure>}
  
  Example for ResourceCmd=SQL and DestinationCreationMode=TABLE_CREATE:
  CREATE TABLE menu(course CHAR(10), item CHAR(20), price INTEGER);

Message examples for DBRecordUpdate

Message examples with SQL statements

Table 6: DBRecordUpdate message with SQL statement (Derby database example)

Custom Msg Header	CREATE / DROP table menu in DB SampleDb	Insert a record in table menu of SampleDb	Update a record in table menu of SampleDb	Update a record; insert if not existent in table menu of SampleDb
MessagePurpose	DBRecordUpdate	DBRecordUpdate	DBRecordUpdate	DBRecordUpdate
TransportType	DB	DB	DB	DB
ResourceType	DBResource	DBResource	DBResource	DBResource
DestinationPath (example for Derby DB)	DBURI:’jdbc:derby:datatrans/inbound/SampleDb;create=true’;DRIVER_CLASS:’ org.apache.derby.jdbc.EmbeddedDriver’ Example DestinationPath for DB2: DBURI:’jdbc:db2:// localhost:50000/SampleDb’;DRIVER_CLASS:’com.ibm.db2.jcc.DB2Driver’	DBURI:’jdbc:derby:datatrans/inbound/SampleDb’;DRIVER_CLASS:’ org.apache.derby.jdbc.EmbeddedDriver’	DBURI:’jdbc:derby:datatrans/inbound/SampleDb’;DRIVER_CLASS:’ org.apache.derby.jdbc.EmbeddedDriver’	DBURI:’jdbc:derby:datatrans/inbound/SampleDb’;DRIVER_CLASS:’ org.apache.derby.jdbc.EmbeddedDriver’
DestinationName	menu	menu	menu	menu
Credentials	User:dbuser;Password:dbpasswd	User:dbuser;Password:dbpasswd	User:dbuser;Password:dbpasswd	User:dbuser;Password:dbpasswd
ResourceCmd	SQL	SQL	SQL	SQL
DestinationCreationMode	TABLE_CREATE TABLE_DROP	INSERT	UPDATE	UPDATE_INSERT
Payload == Executed SQL statements (Payload contains any JDBC prepared statement w/o CONNECT and DISCONNECT)	For table creation: CREATE TABLE menu(course CHAR(10), item CHAR(20), price INTEGER); Data type DOUBLE can also be used. For table deletion: DROP TABLE menu;	INSERT INTO menu VALUES ('appetizer','baby greens',7); INSERT INTO menu VALUES ('entree','lamb chops ',6); INSERT INTO menu VALUES ('dessert','creme brulee',14);	price = price + 5 WHERE course='appetizer'; UPDATE menu SET price = price - 1 WHERE course='entree'; UPDATE menu SET price = price + 2 WHERE course='dessert'	UPDATE menu SET price = price + 5 WHERE course='appetizer1'; INSERT INTO menu VALUES('appetizer1','baby greens1',5) 2 separate steps: a) UPDATE menu SET price = price + 5 WHERE course='appetizer1'; If UPDATE fails then b) INSERT INTO menu VALUES('appetizer1','baby greens1',5)
Comment	Sequence of SQL commands (e.g. SQL script) will be executed in separate prepared statements	Fails if table does not exist	Fails if record with course=appetizer does not exists	Inserts new record if not exists

Note: The provided SQL commands will be executed by the JDBC Resource Adapter which automatically surrounds them with SQL CONNECT and DISCONNECT statements.



Message examples with WHERE clause and data map

(see <XPDinteg_DBdata_xml_structure> )

Table 7: DBRecordUpdate message with WHERE clause (Derby database example)

Custom Msg Header	Create / Drop table menu in DB SampleDb	Insert a record in table menu of SampleDb	Update a record in table menu of SampleDb	Update a record; insert if not existent in table menu of SampleDb
Message Purpose	DBRecordUpdate	DBRecordUpdate	DBRecordUpdate	DBRecordUpdate
Transport Type	DB	DB	DB	DB
Resource Type	DBResource	DBResource	DBResource	DBResource
Destination Path	DBURI:’jdbc:derby:datatrans/inbound/SampleDb;create=true’;DRIVER_CLASS:’ org.apache.derby.jdbc.EmbeddedDriver’ Example DestinationPath for DB2: DBURI:’jdbc:db2:// localhost:50000/SampleDb’;DRIVER_CLASS:’com.ibm.db2.jcc.DB2Driver’	DBURI:’jdbc:derby:datatrans/inbound/SampleDb’;DRIVER_CLASS:’ org.apache.derby.jdbc.EmbeddedDriver’	DBURI:’jdbc:derby:datatrans/inbound/SampleDb’;DRIVER_CLASS:’ org.apache.derby.jdbc.EmbeddedDriver’	DBURI:’jdbc:derby:datatrans/inbound/SampleDb’;DRIVER_CLASS:’ org.apache.derby.jdbc.EmbeddedDriver’
Destination Name	menu	menu	menu	menu
Credentials	User:dbuser;Password:dbpasswd	User:dbuser;Password:dbpasswd	User:dbuser;Password:dbpasswd	User:dbuser;Password:dbpasswd
Resource Cmd	XPDINTEG_DBXML	XPDINTEG_DBXML	XPDINTEG_DBXML	XPDINTEG_DBXML
Destination Creation Mode	TABLE_CREATE TABLE_DROP	INSERT	UPDATE	UPDATE_INSERT
Payload	For table creation: <CREATE_TABLE_SAMPLE_DATA> (see Listing 7) For table deletion: <DROP_TABLE_SAMPLE_DATA> (see Listing 9)	<INSERT_SAMPLE_DATA> (see Listing 10)	<UPDATE_SAMPLE_DATA> (see Listing 11)	<UPDATE_SAMPLE_DATA> (see Listing 13)
Executed SQL statements (Payload contains any Expeditor integrator database commands w/o CONNECT and DISCONNECT)	For table creation: CREATE TABLE menu(course CHAR(10), item CHAR(20), price INTEGER); Data type DOUBLE can also be used. For table deletion: DROP TABLE menu;	INSERT INTO menu VALUES ('appetizer','baby greens',7),('entree','lamb chops ',6),('dessert','creme brulee',14);	UPDATE menu SET ’price = price + 1’ WHERE ’course = appetizer’;	2 separate steps: a) UPDATE menu SET ’price = price + 0.5’ WHERE ’course = appetizer’; If UPDATE fails then b) INSERT INTO menu VALUES (’appetizer’ ’ ’ ’0.5’); DISCONNECT;
Comment		Fails if table does not exist	Fails if record with course=appetizer does not exists	Inserts new record if not exists and where clause data can provide data for a full record

Note: The provided SQL commands will be executed by the JDBC Resource Adapter which automatically surrounds them with SQL CONNECT and DISCONNECT statements.

Example XML message which explain how the <XPDinteg_DBdata_xml_structure> is used within XML messages are provided in APPENDIX A – Example Messages.

Listing 7: <CREATE_TABLE_SAMPLE_DATA> XML example included in the payload of the TABLE_CREATE message (according to the XPDinteg_DBdata_xml_structure)


Note: This data structure must be escaped within the <text> tag of an XML message. Listing 8 shows the <text> tag snippet of an example XML message which includes the <XPDinteg_DBdata_xml_structure> in its payload. Only white spaces should be used (e.g. no tabs) within in the payload.

Listing 8: <XPDinteg_DBdata_xml_structure> example for creating table menu (snippet for <text> tag of XML message)


The price data field could also be of type double (e.g. <create-clause>course CHAR(10), item CHAR(20), price DOUBLE</create-clause>)

Listing 9: <DROP_TABLE_SAMPLE_DATA> XML example included in the payload of the TABLE_DROP message (according to the XPDinteg_DBdata_xml_structure as snippet for <text> tag of XML message)



Listing 10: <INSERT_SAMPLE_DATA> XML example included in the payload of the INSERT message (according to the XPDinteg_DBdata_xml_structure)



Listing 11: <UPDATE_SAMPLE_DATA> XML example for data included in the payload of the UPDATE message (according to the XPDinteg_DBdata_xml_structure)


Note: Multiple updates must be enclosed in separate <update> tags. Multiple <set-clause> statements can belong to one <where-clause>.

Listing 12: <XPDinteg_DBdata_xml_structure> example for creating table menu (snippet for <text> tag of XML message)



Listing 13: <UPDATE_INSERT_SAMPLE_DATA> XML example for data included in the payload of the UPDATE_INSERT message (according to the XPDinteg_DBdata_xml_structure)

DBRecordSelect Messages

Message Header Properties

The following Custom Message Header properties are available for messages sent from back-end messaging system to Expeditor integrator runtime (see Table 3 in chapter 2.4.2 Supported Custom Header Properties for Inbound Messages also):

• DestinationPath=DBURI:’<uri_name>’;DRIVER_CLASS:’<driver_class_path_and_name>’
  (names contain forward slashes only!)
  
  Example for Derby: DBURI:’jdbc:derby:datatrans/inbound/SampleDb;create=true’;DRIVER_CLASS:’org.apache.derby.jdbc.EmbeddedDriver’
  
  Example for DB2: DBURI:’jdbc:db2://localhost:50000/SampleDb’;DRIVER_CLASS:’com.ibm.db2.jcc.DB2Driver’
  
• DestinationName=<db_table_name>
  
• Credentials=User:<DbUser>;Password:<DbPassword>
  
• ResourceCmd=SQL | XPDINTEG_DBXML | XML
• SQL – message payload contains SQL command as a string
• XPDINTEG_DBXML – message payload contains <XPDinteg_DBdata_xml_structure> (see Listing 4 in chapter 2.5.2 Expeditor integrator XML Data Structure for DB Operations)
• (see chapter 2.5.1 Supported Data Formats for JDBC Resource Access)
  
  
• DestinationCreationMode=not used
  
• Payload=<XPDinteg_DBdata_xml_structure >
  
  

Note: The message payload will only support the XPDinteg_DBdata_xml_structure by default (Listing 4 in chapter 2.5.2 Expeditor integrator XML Data Structure for DB Operations). For customization purposes, this structure could be transformed into another (XML) structure by adding a custom ACS Activity to the DbRecordSelect flow:

Message examples for DBRecordSelect

Messages from the back-end messaging system can carry queries for database resources. The result set is created and is sent back to the messaging back-end within defined DBRecordSelect messages (see Table 4 in chapter 2.4.3 JMS Custom Header Creation for Messages from Expeditor integrator to Back-end (outbound)).
Table 8 shows an example for selecting records from table menu of Derby database SampleDb.

Table 8: Derby DB examples for DBRecordSelect messages and corresponding SQL statements

Custom Msg Header FOR: Select record(s) in table menu of SampleDb	SQL statement provided in Payload	WHERE clause provided
MessagePurpose	DBRecordSelect	DBRecordSelect
TransportType	DB	DB
ResourceType	DBResource	DBResource
DestinationPath	DBURI:’jdbc:derby:datatrans/inbound/SampleDb’;DRIVER_CLASS:’org.apache.derby.jdbc.EmbeddedDriver’ Example DestinationPath for DB2: DBURI:’jdbc:db2://localhost:50000/SampleDb’;DRIVER_CLASS:’com.ibm.db2.jcc.DB2Driver’ and for Oracle DB: DBURI:'jdbc:oracle:thin:@dbserver.sample.com:1521:testdb';DRIVER_CLASS:'oracle.jdbc.OracleDriver'	DBURI:’jdbc:derby:datatrans/inbound/SampleDb’;DRIVER_CLASS:’org.apache.derby.jdbc.EmbeddedDriver’
DestinationName	menu	menu
Credentials	User:dbuser;Password:dbpasswd	User:dbuser;Password:dbpasswd
ResourceCmd	SQL	XPDINTEG_DBXML
DestinationCreationMode	-	-
Payload	SELECT * from menu;	<SELECT_SAMPLE_DATA> (see Listing 14)
Executed SQL statements	CONNECT 'jdbc:derby:datatrans\inbound\SampleDb; SELECT * from menu; DISCONNECT;	CONNECT 'jdbc:derby:datatrans\inbound\SampleDb; SELECT * from menu; DISCONNECT;
Comment	Fails if table does not exist. Returns null / 0 ResultSet if no matching record is available. Result set is later assembled in the DatabaseSerializationActivcity, see Listing_5 (the interpreted selector clause is also included for reference)	Fails if table does not exist. Returns null / 0 ResultSet if no matching record is available. Result set is later assembled in the DatabaseSerializationActivcity, see Listing 16 (the interpreted selector clause is also included for reference)

Listing 14: <SELECT_SAMPLE_DATA> example for record data included in the message payload (according to the <XPDinteg_DBdata_xml_structure>)


Note: This data structure must be escaped within the <text> tag of an XML message. Listing 15 shows the <text> tag snippet of an example XML message which will trigger the creation of a reply message that contains the ResultSet as @nowiki@105in its payload.


Listing 15: <XPDinteg_DBdata_xml_structure> example for selecting record(s) from table menu (snippet for <text> tag of DBRecordSelect XML message)



Listing 16: <RESULTSET_SAMPLE_DATA> for record data included in the reply message payload (according to the <XPDinteg_DBdata_xml_structure>)

Using third-party drivers for use with-in integrator

Expeditor integrator contains all required driver classes for using the local Derby database. For accessing other databases, their specific JDBC driver classes must be added. The following chapters describe the required steps for IBM DB2 and Oracle database.

IBM DB2 installation steps

The following drivers are required for accessing DB2 (valid for v9.5.0). They are included in DB2 installation package:

• db2jcc.jar
• db2jcc_license_cu.jar

Follow these steps to add them to your Expeditor integrator runtime:

1. Create Lotus Expeditor Client-Services Project using the Project Wizard (or an Eclipse plug-in project), e.g. com.ibm.rcp.integrator.db2.driver.
1. Use provided default settings (no additional plug-in properties set)
2. Select Core Target as target platform and the offered Target Features
3. No additional Target template selected
2. Import the driver JAR files for DB2 on project root level (e.g: db2jcc.jar and db2jcc_license_cu.jar).
3. Include the imported database driver (JAR file) in the plug-in CLASSPATH. Edit the MANIFEST.MF file and select the Runtime tab.
1. a. Add the JAR to the CLASSPATH section.
2. b. In the Exported Packages section, export all the packages included in the JAR.
4. Create an Eclipse Feature Project, e.g. by using the project wizard (e.g. name com.ibm.rcp.integrator.db2.driver.feature). Include the plug-in created above in the feature. Set the colocation-affinity of the feature to com.ibm.rcp.platform.feature (Go to the Installation tab and provide the feature ID com.ibm.rcp.platform.feature in the “To collocate this feature with another feature” field.).
5. Create an Update Site Project (e.g. by using the project wizard). Edit the site.xml file and add the generated feature. Build the update site by clicking on Build All. Export the created update site to the file system.
6. Include the created feature and plug-in of the created update site folder in the Expeditor integrator installer:
1. Copy the feature jar into updates/platform/features and plug-in into updates/platform/plugins folders respectively of the Expeditor integrator installer.
2. Add the feature to the site.xml in updates/platform/site.xml:
   <feature url="features/com.ibm.rcp.integrator.db2.driver.feature_1.0.0.jar" id="com.ibm.rcp.integrator.db2.driver.feature" version="1.0.0">
   <category name="runtimes"/>
   </feature>
3. Update the install manifest file, e.g. desktop/install/deploy/install.xml:
   <feature id="com.ibm.rcp.integrator.db2.driver.feature" version="1.0.0" size="4" download-size="4" match="compatible" action="install" shared="false"/>\
7. Other installation options options:
1. For installation after deployment, the Expeditor Client Manager could be used to install this feature.
2. For manual installation in an existing Expeditor integrator instance, the Provisioning API could be used, e.g. by entering the following command in the OSGi console window:
   prov ie <feature_id> <version> file:///c:/<path>/site.xml
   where file:/ points to the site.xml in the exported update site above.
   (e.g. prov ie com.ibm.rcp.integrator.db2.driver.feature 1.0.0 file:/c:/tmp/site.xml)
   
   Note: In this case, Expeditor integrator must be re-started for this change to take effect.

Oracle 9i driver installation steps

For using third-party drivers, e.g: ORACLE 9i Release 2 drivers, follow these steps:

1. Create Lotus Expeditor Client-Services Project using the Project Wizard (or an Eclipse plug-in project), e.g. com.ibm.rcp.integrator.oracle.driver. Import the driver JAR files for the customer database on project root level (e.g: ojdbc14.jar).
1. Use provided default settings (no additional plug-in properties set)
2. Select Core Target as target platform and the offered Target Features
3. No additional Target template selected
2. Include the imported database driver (JAR file) in the plug-in CLASSPATH. Edit the MANIFEST.MF file and select the Runtime tab.
1. Add the JAR to the CLASSPATH section.
2. In the Exported Packages section, export all the packages included in the JAR.
3. Create an Eclipse Feature Project, e.g. by using the project wizard (name com.ibm.rcp.integrator.oracle.driver.feature). Include the plug-in created above in the feature. Set the colocation-affinity of the feature to com.ibm.rcp.platform.feature (Go to the Installation tab and provide the feature ID com.ibm.rcp.platform.feature in the “To collocate this feature with another feature” field.).
4. Create an Update Site Project (e.g. by using the project wizard). Edit the site.xml file and add the generated feature. Build the update site by clicking on Build All. Export the created update site to the file system.
5. Include the created feature and plug-in of the created update site folder in the Expeditor integrator installer:
1. Copy the feature jar into updates/platform/features and plug-in into updates/platform/plugins folders respectively of the Expeditor integrator installer.
2. Add the feature to the site.xml in updates/site.xml:
   <feature url="features/com.ibm.rcp.integrator.oracle.driver.feature_1.0.0.jar" id="com.ibm.rcp.integrator.oracle.driver.feature" version="1.0.0">
   <category name="runtimes"/>
   </feature>
3. Update the install manifest file, e.g. desktop/install/deploy/install.xml:
   <feature id="com.ibm.rcp.integrator.oracle.driver.feature" version="1.0.0" size="4" download-size="4" match="compatible" action="install" shared="false"/>\
6. Other installation options options:
1. For installation after deployment, the Expeditor Client Manager could be used to install this feature.
2. For manual installation in an existing Expeditor integrator instance, the Provisioning API could be used, e.g. by entering the following command in the OSGi console window:
   prov ie <feature_id> <version> file:///c:/<path>/site.xml
   where file:/ points to the site.xml in the exported update site above.
   (e.g. prov ie com.ibm.rcp.integrator.oracle.driver.feature 1.0.0 file:/c:/tmp/site.xml)
   
   Note: In this case, Expeditor integrator must be re-started for this change to take effect.

Post-installation steps

Use the appropriate Expeditor integrator property DestinationPath for providing the database driver name:

• DB2:
  DBURI:'jdbc:db2://<hostname>:<port>/<dbname>';DRIVER_CLASS:'com.ibm.db2.jcc.DB2Driver'
• Oracle:
  DBURI:'jdbc:oracle:thin:@<hostname>:<port>:<dbname>';DRIVER_CLASS:'oracle.jdbc.OracleDriver'
  Please, also remember to provide the correct credentials in the Credentials property.

Using the Outbound HTTP Adapter

The HTTP Adapter provides access to resources located on an HTTP server. Depending on the security model on the HTTP server, resources are

• written (HTTP Put),
• read (HTTP Get, which can be initiated by a local Resource Adapter which polls for a given resource or by a Request Message sent from the back-end)
• updated (HTTP Post) or
• deleted (HTTP Delete).

These resources can be files which are located on the directory of the HTTP server or any automatically created response (e.g. an XML stream created by CGI scripts). It is important to configure the Expeditor integrator HTTP Adapter appropriately to address the different resources. Currently, only binary objects and XML structures which comply with Expeditor XPDINTEG_DB_XML are supported.

Since the HTTP Adapter is based on the Apache client all Apache compliant HTTP servers should be accessible. Currently, Expeditor integrator is compliant to

Apache HTTP Server v2.2 with support of:

• HTTP and HTTPs and
• the following HTTP Authentication methods:
• HTTP Basic Authentication
• Digest Access Authentication

All HTTP related Expeditor integrator Application Control Service Activities map to the 4 HTTP CRUD methods and can be invoked by the 4 custom message header values for MessagePurpose.

Table 9: MessagePurpose, queues, ACS Flows and Dispatcher Service changes for HTTP outbound support

MessagePurpose / TransporType	ACS Flow that is triggered by default / Trigger topic issued by dispatcher/HttpAdapter / dispatcher target resource	Main Activity for HTTP operation	Comment
HttpPost / HTTP	Default_PostHttpResources / "com/ibm/integrator/flowtriggerevent/HttpPost/HTTP/HttpResource/dispatcher" / JndiDestinationKey="jms/XPDinteg_MsgToHttpQ”	XPDINTEG_HTTP_POST	UPDATE method which updates a resource on the HTTP Server
HttpPost / HTTPS	Default_PostHttpsResources / "com/ibm/integrator/flowtriggerevent/HttpPost/HTTPS/HttpResource/dispatcher" / JndiDestinationKey="jms/XPDinteg_MsgToHttpsQ”
HttpGet / HTTP	Default_ReqGetHttpResources / "com/ibm/integrator/flowtriggerevent/HttpGet/HTTP/HttpResource/dispatcher" / JndiDestinationKey="jms/XPDinteg_ MsgToHttpQ”	XPDINTEG_HTTP_GET	-Triggered by incoming request message -Read method which reads a resources on the HTTP Server -Retrieved resource is put into message and send to local “jms/XPDinteg_HttpToMsgQ”
HttpGet / HTTPS	Default_ReqGetHttpsResources / "com/ibm/integrator/flowtriggerevent/HttpGet/HTTPS/HttpResource/dispatcher" / JndiDestinationKey="jms/XPDinteg_MsgToHttpsQ”
HttpGet / HTTP(s)	Sample_PickupHttp(s) SampleResources / "com/ibm/integrator/flowtriggerevent/HttpGet/HTTP(S)/SampleHttpResource/HttpAdapter" / JndiDestinationKey="jms/XPDinteg_MsgToHttpsQ”	XPDINTEG_HTTP_GET	-Flow triggered by SampleHttpResource HTTP Adapter (configured in XPDinteg.xml)
HttpPut / HTTP	Default_PutHttpResources / "com/ibm/integrator/flowtriggerevent/HttpPut/HTTP/HttpResource/dispatcher" / JndiDestinationKey="jms/XPDinteg_MsgToHttpQ”	XPDINTEG_HTTP_PUT	Create method which creates a resource on the HTTP Server (Note: HTTP Put only supports DestinationCreationMode=Overwrite)
HttpPut / HTTPS	Default_PutHttpsResources / "com/ibm/integrator/flowtriggerevent/HttpPut/HTTPS/HttpResource/dispatcher" / JndiDestinationKey="jms/XPDinteg_MsgToHttpsQ”
HttpDelete / HTTP	Default_DeleteHttpResources / "com/ibm/integrator/flowtriggerevent/HttpDelete/HTTP/HttpResource/dispatcher" / JndiDestinationKey="jms/XPDinteg_MsgToHttpQ”	XPDINTEG_HTTP_DELETE	DELETE method which deletes a resource on the HTTP server
HttpDelete / HTTPS	Default_DeleteHttpsResources / "com/ibm/integrator/flowtriggerevent/HttpDelete/HTTPS/HttpResource/dispatcher" / JndiDestinationKey="jms/XPDinteg_MsgToHttpsQ”

Listing 17: HTTP Header syntax

HTTP headers:

• GET path_to_file_SampleHttpFile.html HTTP/1.1
• POST path_to_sample.jsp HTTP/1.1
• HEAD path_to_file_index.html HTTP/1.1
• DELETE path_to_file_to_delete.html HTTP/1.1

The GET method simply requests the specified resource and does not allow a message body. The HEAD query is like GET but requests only the header part of the response. The POST method allows a message body and is designed to work with a CGI URL.


Listing 18: Get example request configured in the HttpHeaderConfigFile


The following listing shows a Post request example which is provided in the HttpHeaderConfigFile. Note, that the HTTP Request body must be appended to the request header before sending the request to the HTTP Server. The incoming ResourceData object of type FILE is used as HTTP Request body.

Listing 19: Post example request configured in HttpHeaderConfigFile


Note: The HttpHeaderConfigFile should only be used if the HTTP communication is not secured. Otherwise a potential security threat is exposed by having the HTTP credentials stored in this file.

Response formats
The content of the HTTP response from the HTTP server is taken and interpreted as file resource. The HttpGetActivity extracts the body of the HTTP Response and passes it on as ResourceData object of type FILE. Any ACS Activity can follow that takes this object type as input. The response in Listing 20 is passed on as FILE with the content “Hallo, this is our test.”. This could be detached in the

Listing 20: HTTP Response Example


For compatibility reasons to any JDBC Adapter related ACS Activities, the following HTTP Response body should be used by the HTTP Server (see definition of <XPDinteg_DBdata_xml_structure> in chapter 2.5.2 Expeditor integrator XML Data Structure for DB Operations):


Listing 21: HTTP Response example using <XPDinteg_DBdata_xml_structure>


This HTTP Response body is required for the MessageToDatabaseXPDinegDBXMLActivity (XPDINTEG_MESSAGE_TO_DB_XPDINTEG_XML).

HTTP Communication Error Handling

Table 10: Expeditor integrator HTTP error handling

HTTP Response	Expeditor integrator ACS flow error	Expeditor integrator reaction
Error 500 - Internal Server Error	UNKNOWN_PROBLEM_REASON_CODE	Activity retries accessing the server. Configurable in ACS section of XPDinteg.xml, e.g.: <param name="RetryAttempts" value="200"/> <param name="RetryInterval" value="5000"/>
		InvalidMessageFailureAction
		RollbackMessageAction

Limitations of HTTP Adapter Flows

The HTTP (outbound) Adapter in Expeditor integrator is developed for simple HTTP Server target systems (e.g. scale systems which are accessible through HTTP rather then FTP). Extensive HTTP sessions with large bi-directional traffice are not expected. Furthermore, due to the limitations of HTTP protocol (stateless), the implementation of the read from HTTP Server and write to HTTP Server methods is not fully transactional:

• The XPDINTEG_HTTP_POST/XPDINTEG_HTTP_PUT activity does a POST/PUT respectively on the target HTTP server in the execute() method. The concreteCommit() of the XAResources created by both the activities is not used by POST/PUT as there is no way to rollback the HTTP request.
• Because of this limitation, even if any activity, succeeding the above two activities in a flow, fails, the POST/PUT request can still be successful.

Using the REST Adapter for Sending Data (inbound)

The REST (REpresentational State Transfer) Adapter provides data access to the Expeditor integrator runtime through HTTP. In addition to the messaging channel access, the REST Adapter allows for exchanging message content with Expeditor integrator, but uses HTTP. This is important for the integration of other not-messaging-based legacy systems (e.g. terminals, PDAs).

Figure 20 shows the REST Adapter architecture. The HTTP Request is taken and transformed into an Expeditor integrator compliant message. This message is then placed into the ReqInQ or CtrlQ in the same way as the messaging system would do it. From there on, the previous HTTP request is handled in the same way as any incoming message. The process of the HTTP request message is tracked in the Persistence Service. This information is taken to provide an appropriate status response to the initial HTTP Request.

Figure 20: HTTP requests based on the Expeditor integrator request schema can be used to send data to Expeditor integrator. These requests are converted into Expeditor integrator messages and are put into the ReqInQ (by default) for further processing.


All HTTP requests to the REST Adapter can be secured with username and password. Please, refer to the Installing and Configuring the IBM Lotus Expeditor integrator platform for configuration details (see Ref_1).

HTTP Request Schema for REST Adapter

The REST resource for the Expeditor integrator REST interface is a Request. A Request in Expeditor integrator terms maps onto a request message as sent by the enterprise via JMS and the bridge. The HTTP URI scheme for a Request Resource is as follows:

where <transaction id> is the unique transaction identifier given by the requesting application. The Expeditor integrator context root is set in the configuration of the implementing Client Services Web Project.

Creating a new Request

As per standard REST semantics, the creation of a new integrator Request is made using an HTTP POST and the URI scheme from above. Within the HTTP request, the Expeditor integrator Request headers as defined for requests made via JMS are included in the HTTP headers, prefixed with IBMIntegrator-. For example, the following shows how the header would look for the TransferType header:

The following is the retail example for the Price Update request headers made using the REST interface:

Listing 22: HTTP Request header for Price Update request in the retail industry example.



Within the doPost() method of the Request Servlet, the HTTP headers will hence be read and the Expeditor integrator specific headers will be extracted to create the JMS message. Note, that all of the provided headers will be set as String properties on the JMS message. This means that the data format supplied in the HTTP headers must be a supported format for the data as it will be read on receipt e.g. numbers must be correctly formatted. In the above example, EndOfData JMS Custom Header property will be read from the JMS message on receipt as Boolean; therefore it must be set on the HTTP header in one of the supported Java string formats for a Boolean value (i.e. true or false). An exception will be thrown at runtime if the values cannot be translated.

Any payload for the request (such as the contents of a file) will be provided as the payload of the HTTP POST. The HTTP Content-Type header will be set as follows to indicate whether the data is binary or text:

• text/plain;charset=<charset>
  for encoded textual file content where <charset> is the character encoding for the payload, e.g. UTF-8.
• application/octet-stream
  for raw binary content.

For more information on HTTP content types, see http://en.wikipedia.org/wiki/Internet_media_type#List_of_common_media_types .

Note: The presence of the Content-Type header and the inclusion of the transaction identifier in the request URI means that any explicit Expeditor integrator TransferMode and TransactionId JMS Custom Header properties will be ignored to avoid confusion.

A successful HTTP request to create an Expeditor integrator Request will respond with an HTTP 200 OK response.

Case In-sensitiveness of HTTP headers

Since the HTTP request headers are case in-sensitive, we can’t rely on the Lotus Expeditor Client WebContainer to retain the case. So, a mapping like below is needed:

<param name="ibmxpdintegrator-messagepurpose" value="MessagePurpose" type="String"/>
<param name="ibmxpdintegrator-buildinterval" value="BuildInterval" type="Long"/>
<param name="ibmxpdintegrator-endofdata" value="EndOfData" type="Boolean"/>

Please, refer to the Installing and Configuring the IBM Lotus Expeditor integrator platform for more configuration details (see Ref_1).

Routing

Routing of the created messages by the Request Servlet (Figure 20) is done through the mapping between the MessagePurpose and JNDI key for a destination queue/topic, e.g.
<routing>
<messagepurpose value="FileTransfer" destination="jms/XPDinteg_ReqInQ"/>
<messagepurpose value="HouseKeeping" destination="jms/XPDinteg_CtrlQ"/>
…
</routing>

Please, refer to the Installing and Configuring the IBM Lotus Expeditor integrator platform for more configuration details (see Ref_1).

Querying the status of a Request

HTTP GET is used with the URI scheme described above to query the status of Expeditor integrator REST Request. No specific additional headers are required in the HTTP request. The response to a successful request is an HTTP 200 OK response with a Javascript Object Notation (JSON ) payload containing details of the status of the initial Request. JSON is a simple data format that is not only highly suitable for consumption by web browser applications but also by richer programming languages. For more information see http://www.json.org/ .

The JSON payload will be structured as follows:
{
status: “<transaction status>”
}

where <transaction status> is the transaction status as returned by the Monitor Service (described elsewhere in this document). The HTTP Content-Type header will be set to application/json accordingly.

Error responses

For both POST and GET, error conditions will be indicated by giving an appropriate HTTP response code together with a JSON payload containing diagnostic information. The response will have an HTTP Content-Type header set to application/json and a payload structured as follows:
{
message: “<diagnostic message>”
}
where <diagnostic message> is a descriptive string to indicate the cause of the problem. A table of the HTTP response codes used specifically by the Expeditor integrator can be found in chapter 2.7.1.5 REST Adapter Response Codes.

REST Adapter Response Codes

For both POST and GET Requests, error conditions will be indicated by giving an appropriate HTTP response code and diagnostic information. Table 11 shows the HTTP response codes used specifically by Expeditor integrator.

Table 11: REST interface diagnostic message meaning

HTTP response code	Expeditor integrator meaning	diagnostic message
500	Internal Server error. An unexpected exception occurred when processing the REST request. The diagnostic message will contain any exception message and an entry should have been written to the error log.	Any exception messages caught by the REST interface.
404	Not found. Expeditor integrator could not find any record of the Request with the provided transaction identifier.	Could not find any record of the Request with the provided transaction identifier <transaction id>.
400	Bad request. The transaction identifier of the request is either missing or malformed.	The transaction identifier of the request is either missing or malformed.

Note: Other HTTP response codes may be returned by the Lotus Expeditor Client WebContainer. For example, if access control is implemented where upon a 403 response (forbidden) would occur for bad or missing credentials. Similarly, a malformed URI would result in a 404 response. In each of these cases, the payload would not be in JSON format. A full catalogue of HTTP response codes can be found at http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html .

Use the 4690 Persistence adapter to create messaging applications running on the IBM 4690 POS controller

The following chapters describe how to embed and configure the 4690 Persistence adapter into a Buffered JMS Messaging Client application running on the IBM 4690 POS controller. The file system of this POS (Point of Sale) system supports distributing files between interconnected POS controllers using file system attributes. 4690 specific Java I/O classes allow managing these attributes. The 4690 Persistence adapter is using these classes to allow setting these attributes. This allows an “out-of-the-box” distribution of the message buffer of the JMS Messaging Client application to implement high availability solutions for the POS controllers.

Overview

The 4690 Persistence adapter is a library that can be embedded into JMS Messaging Clients applications to persist messages on the 4690 specific file system supporting its distribution features.

Please refer to the Whitepaper http://www.ibm.com/developerworks/lotus/documentation/retailjms/ for a detailed background of “how and when JMS Buffered Messaging Clients are used”. Please notice that the whitepaper refers to an older version of the Persistence adapter. Class names and names of configuration parameters might have changed, but the concepts are up-to-date.

What addresses the “IBM 4690 JMS Persistence Adapter” ?

How to embed the 4690 persistence adapter

This chapter requires knowledge of how to create JMS Messaging Client application. Details on this can be found also the whitepaper mentioned above.

The 4690 Persistence adapter is packaged with IBM Lotus Expeditor integrator. The library can be found in the directory /tools. The file is named 4690pers.jar.

This jar file must be integrated into the JMS Messaging Client application that should run on the 4690 POS controller.

· Add the 4690pers.jar to the classpath of the JMS Messaging Client application.
· Call the correct Persistence class name in the JMS Messaging Client application code. The persistence class name is: com.ibm.rcp.integrator.4690persistence.Pos4690FilePersistence.
The listing below shows a corresponding code snippet to use the Persistence adapter.

{code}
iConnFactory = jmsFactory.createConnectionFactory();
iConnFactory.setBooleanProperty(MQTTConstants.MQTT_BUFFERED, true);
iConnFactory.setIntProperty(MQTTConstants.MQTT_OUTBOUND_BUFFER_SIZE, BUFFER_SIZE);
set user defined persistence
iConnFactory.setIntProperty(MQTTConstants.MQTT_PERSISTENCE_TYPE, MQTTConstants.MQTT_PERSISTENCE_TYPE_USER_DEFINED);
iConnFactory.setStringProperty(MQTTConstants.USER_DEFINED_PERSISTENCE, “com.ibm.rcp.integrator.4690persistence.Pos4690FilePersistence”);

{code}

How to configure the Persistence Adapter

The 4690 Persistence adapter supports the following configuration properties. These are set as Java system properties.

The properties are:

· DATA_DIR: describes the location of the message store base directory.
Example:
DATA_DIR=Q
Client specific message store directory: is the first letter of the ClientName provided when instantiating the JMS Buffered Client.

c:\Q\B\0\1.m → shortest possible message full path name contains already 12 characters.

· POS4690_ATTRIBUTE_SETTINGS: the attributes for the 4690 distributed file system. Its a structured String with the following syntax: ACCESS_TYPE,FILETYPE,DISTRIBUTIONMETHOD
The separator is a colon ","
Allowed values for ACCESS_TYPE:

· EXCLUSIVE_ACCESS

· SHARED_READ_ACCESS

· SHARED_READ_WRITE_ACCESS

Allowed values for FILE_TYPE:

· MIRRORED_FILE

· COMPOUND_FILE

Allowed values for DISTRIBUTIONMETHOD:

· DISTRIBUTE_ON_UPDATE

· DISTRIBUTE_ON_CLOSE

If this property is not provided the following default value is applied:

EXCLUSIVE_ACCESS,COMPOUND_FILE,DISTRIBUTE_ON_CLOSE

Example for start-up command using the system properties

{code}

java -DDATA_DIR=./S -DPOS4690_ATTRIBUTE_SETTINGS=EXCLUSIVE_ACCESS,COMPOUND_FILE,DISTRIBUTE_ON_CLOSE -jar yourjar.jar

{code}

Logging

The 4690 Persistence adapter uses a java.util.logging-Logger for logging purposes. It creates a logger with the following name: "com.ibm.rcp.integrator.4690persistence".

The log level and the log handlers can be set by the JMS Messaging Client application instantiating the messaging client.

The following logging policy is applied internally:

· Severe logging is used to report errors.

· Info logging is used to repoFinest logging is used to report method internal steps in complex methodsrt usage of the default properties and version information.

· Fine logging is used to report “entering” and “leaving” a method.

· Finest logging is used to report method internal steps in complex methods

Runtime behavior of the Persistence adapter

Normal runtime behavior

The Persistence adapter persists every single message as a file inside the directory specified as Data_Dir. Below the data directory a sub directory is created with the first character of the ClientID of the JMS Messaging Client. Inside this directory the single messages are persisted. In case the same Data_Dir is shared by several Messaging Client applications, messages are separed by this mechanism. Please make sure to name the messaging clients differently. The first letter must be different; otherwise several JMS Messaging Client applications access the same message store causing unpredictable behavior. This “First-letter” limitation was introduced due to the limitations on the total file name lengths of the 4690 specific file system. It allows only full path names up to 26 characters. The short client directory name allows spending more characters on the message name itself.

Due to performance reasons, a further directory structure is introduced. Below the the Messaging Client folder, numbered folders are created. In each folder 1000 messages are persisted.

Message files are persisted with the extension .m. During the sending procedure also backup files are created. These files end with .b. In an empty message store you should not find backup files. If you find some, please check the log file for errors being reported by the Persistence adapter.

Example for the directory and message file names:

· Data_Dir=c:/Q, ClientId=PosClient, MessageNumber = 3: message file will be stored in the folder c:/Q/P/0/3.msg

· Data_Dir=c:/Q, ClientId=PosClient, MessageNumber = 2399: message file will be stored in the folder c:/Q/P/2/2399.msg

· Data_Dir=c:/Q, ClientId=Client, MessageNumber = 55399: message file will be stored in the folder c:/Q/C/55/55399.msg

As soon as the JMS Messaging Client application connects to the Lotus Expeditor integrator a message named -1.m is written.

Error situations and limitations

In case of error situations, the Persistence adapter is throwing a com.ibm.mqttclient.utils.persistence.MqttPersistenceException. The exception text describes the nature of the error. In case a MqttPersistenceException occurs, the Persistence adapter was not able to persist or read a message. The JMS Messaging Client application must act accordingly and stop sending messages. Messages losses will occur. The errors are also logged using the above mentioned logger.

One example for an error case:

The Persistence adapater checks the total allowed file name length (26 chars) every time a message is written. If the limit is exceeded, it throws a com.ibm.mqttclient.utils.persistence.MqttPersistenceException with the text “File name exceeds limit. Path name: ”. The JMS Messaging Client application must check for this error. In case of this exception, the Persistence Adapter is no longer able to persist messages. The JMS Messaging Client application must stop sending further messages. There is a high chance, a restart of the JMS Messaging Client application fixes the behaviour as the internal numbering mechanism is restarted inside the IBM messaging client code. Please find further information below.

The IBM Messaging Client libraries theoretically supports to store maximum 2³¹-1 (2.147.483.647) messages at once in the message store. Due to the limitation of the 4690 filesystem (file name: 8+3, max full path length: 26) the theoretical maximum message number is: 99.999.999. You need to consider also the data dir name and Messaging client folder.

Max Message number on the 4690: C:/Q/P/99999/99999999.m

Background information on the IBM messaging client library internal numbering mechanism:

On every startup the IBM messaging client logic determines the smallest unused message ID as next message ID. The message ID is used as file name by the Persistence adapter. Thanks to this mechanism it is hardly possible to run out of message IDs in the lifetime of the JMS Messaging Client application.